Connections

A connection is how traceunified reaches another tool: its address and a credential, held at the organisation level. Each project then chooses what it syncs through the integrations that use it.

Supported tools

Tool	What it does	Credential
Atlassian Jira	Syncs issues both ways	API token, or OAuth 2.0 (3LO)
GitHub	Syncs issues both ways	Personal access token, or OAuth 2.0
Bitbucket Cloud	Links commits and pull requests to the items they name; syncs nothing	API token, or workspace access token

A generic REST connector is built but not offered in this release. A connector is released only once it has run against a live instance of its tool. Asking for one that is not offered is refused with the list of tools that are.

The credential

• It is encrypted before it is stored and never shown again. When you edit a connection, leaving the secret blank keeps the stored one.
• Scope it to what the connection must do. A connection that pushes needs write access, not just read — and its write policy switched on (see below). For GitHub, a fine-grained token needs Issues (read and write) and Metadata on every repository you will route.
• A health check proves it works. A connection that stops authenticating appears in Activity as a setup problem, with its remedy, rather than as a run of failed cycles.

The account the Hub acts as

The first row on the Connections screen is traceunified itself: not something to connect to, but the account the Hub acts as. That account is the one shown on everything the Hub does, in every integration, so an automated write is never mistaken for a person’s.

Reading, then writing

A connection starts read-only. Its write policy is off by default, so it can read from the other tool but never write to it until an organisation administrator opts it in. A connection that must push — create issues, update fields — needs that switched on, and a credential with write access behind it.

Change detection: a status, not a setting

How changes made in the other tool reach traceunified is shown on each connection as a status, with nothing to click:

• Webhook + poll — changes arrive within seconds. The row says whether deliveries are signed, whether the webhook was set up by hand, and when the last delivery arrived.
• Poll — changes arrive on the next poll.

There is no poll-only switch and no “ask for a webhook” button. The poll always runs: every integration asks the other tool what changed on its own interval, with a daily full scan behind it, so nothing is missed without a webhook. A webhook only makes it fast, and the product sets up its own:

• When the connection’s account can manage webhooks — a Jira administrator, or a GitHub or Bitbucket token with webhook permission — traceunified registers a webhook in the other tool, scoped to the projects you route.
• It re-checks it daily and whenever routing changes, recreates it if somebody deletes it, and removes it when the connection goes.
• When the account cannot manage webhooks, the connection runs on the poll alone.

A webhook you made by hand with the URL and secret the connection shows is left alone: the product never overwrites it or registers a second one beside it.

Every delivery is verified against its secret. The connection records when a verified delivery last arrived, so a webhook that has never actually delivered is reported rather than trusted because it was configured.

Code links from Bitbucket

A Bitbucket connection watches repositories rather than syncing items. A commit or pull request whose text names an item’s ID, such as PMS-REQ-001, is linked to that item and listed on it.

• A commit is linked once and kept, because a commit cannot change.
• A pull request follows its current text: remove the ID from it and the link goes.
• IDs are matched only within your organisation, so another customer’s item with the same ID can never be linked.

Who can open it

Connections hold the organisation’s credentials, so the screen is available to organisation administrators only.