Manage connections

Your workspace’s connections are under Settings → Connections. A connection links your workspace to an account at a helpdesk (Zendesk) or to a repository (GitHub, GitLab, Bitbucket). Everyone in the workspace sees the list; only admins connect, disconnect or change a connection.

What each card shows

Each helpdesk, repository provider and issue tracker has one card, connected or not; the connected ones come first. A connected card shows how many accounts or repositories are connected; select it to open the provider’s page, where you see each one, add more, or disconnect one. Select a card that isn’t connected yet to connect it. A card shows its status:

Status	Meaning
Connected	Tracewell can use it.
Error	The provider no longer accepts Tracewell’s access, for example because someone revoked it. The provider’s page says which account or repository; select Connect again there.
Disconnected	Tracewell has no access. Select Connect again on the provider’s page to restore it.
Not connected	Nothing is connected yet.

Cards that say Not available yet are for providers Tracewell can’t connect to yet.

The status is what Tracewell saw the last time it used the connection. Opening the page doesn’t contact the providers.

Use the search field and the filters (Helpdesks, Repositories, Issue trackers) to find a connection; searching for an account or a repository finds its provider’s card as you type.

Connect Zendesk

1. Select the Zendesk card. Once an account is connected, open the card and select Connect an account to add another.
2. Enter your Zendesk subdomain: acme for acme.zendesk.com. Select Continue to Zendesk.
3. Zendesk asks a Zendesk admin to approve the connection. Approve it.
4. Back in Tracewell, a dialog shows the four settings of the Tracewell sidebar app.

The Zendesk page lists your Zendesk accounts. Under each connected account, admins find its knowledge base and the sidebar app’s settings.

Connecting sets up a trigger in Zendesk, so that adding the investigate tag to a ticket starts an investigation.

Install the sidebar app

When you install the Tracewell app in Zendesk, it asks for four settings: Tracewell host, Workspace ID, Connection ID and Signing secret. Copy them from the dialog after connecting, or later from the account on the Zendesk page, under Sidebar app. To change them in Zendesk, in Zendesk Admin Center open Apps and integrations → Apps → Zendesk Support apps → Tracewell → Settings.

If you connect the same account again, the signing secret stays the same and the installed app keeps working. After you disconnect the account and connect it again, the secret is new: enter it in the app’s settings.

Connect repositories

Select the provider’s card; to add repositories of a provider you’ve connected already, open its card and select Add repositories. Tracewell only ever asks for read access.

• GitHub: you choose an organization the Tracewell GitHub App is installed on, or an owner installs it and picks the repositories at GitHub.
• GitLab: you sign in, then pick the repositories in Tracewell.
• Bitbucket: you sign in, then pick a workspace and its repositories in Tracewell.

When you’ve connected repositories, Tracewell opens the provider’s page with them.

Disconnect

1. On the provider’s page, next to the account or repository, open the ⋯ menu and select Disconnect.
2. Tracewell says what disconnecting does at the provider. Select Disconnect.

Provider	What disconnecting does
Zendesk	Removes Tracewell’s trigger and webhook from Zendesk and revokes its access. Agents can’t start investigations from that account until you connect it again.
GitHub	Tracewell stops reading the repository. The GitHub App stays installed on your organization; an owner uninstalls it in GitHub.
GitLab	Tracewell stops reading the repository, and revokes its access in GitLab once no other connected repository uses the same sign-in.
Bitbucket	Tracewell stops reading the repository. Bitbucket has no way for Tracewell to revoke its access: revoke it yourself under Personal Bitbucket settings → Connected apps.

Remove a connection

A disconnected connection stays in the list with its settings, such as the knowledge base, so connecting it again restores them. To forget it:

1. On the provider’s page, next to the disconnected account or repository, open the ⋯ menu and select Remove.
2. Tracewell says what it deletes. Select Remove.

Removing a helpdesk also deletes its investigations and their verdicts. A repository that a helpdesk’s code mapping uses can’t be removed until the mapping points at another repository.

If connecting fails

Tracewell shows why at the top of the page, with Try again.

Tracewell says	What to do
The connect link expired	You took longer than an hour, or opened an old link. Try again.
The connection wasn’t approved	You cancelled at the provider. Try again and approve it.
… didn’t accept the authorization	Try again.
The connect link was started by someone else, or in another workspace	Start connecting from this workspace’s settings yourself.

The pages for GitHub, GitLab and Bitbucket list the messages that only those providers give.