Git integrations

Connect

Administration, Integrations. Three providers:

• GitLab, self-hosted or gitlab.com: a token with read_api; a group token outlives a person leaving
• GitHub, github.com or GitHub Enterprise Server: a fine-grained token with read access to Contents, Pull requests, Actions, Deployments and Metadata, or a classic token with repo
• Bitbucket Cloud: an access token of the workspace, project or repository with read rights, or an account's API token together with its e-mail

Add a connection with a name, the server address (no path), the group, organisation or workspace it covers, the token and the sync interval (default 60 minutes). Tokens are stored encrypted and never shown back. Test checks the connection; Synchronise reads it now. A new connection is saved switched off; nothing is read or received until you switch it On.

How work items are found

Name the work item key in a branch name, commit message or merge request title, for example feature/PAY-12-login. Keys are matched regardless of case, must stand on their own, and link only to work items that exist. The work item's Development section shows the branches, commits, merge or pull requests, builds and deployments; links can also be added by hand.

Webhooks

Synchronisation on a schedule is the fallback. For events within seconds, issue a secret on the connection and add a webhook in the Git server with the webhook address shown (under /api/webhooks/dev/):

• GitLab: paste the secret into Secret token and tick Push, Merge request, Pipeline and Deployment events. GitLab versions that create a signing token instead can paste it into Signing token; the signed timestamp stops replays
• GitHub: content type application/json, the secret, and Pushes, Pull requests, Pull request reviews, Workflow runs and Deployment statuses. The body is signed with HMAC-SHA256
• Bitbucket: the secret, and Repository Push, Build status created and updated, and the pull request events. Bitbucket sends no webhook for deployments; they are read at each synchronisation

Signatures and secrets are compared in constant time. Builds and deployments that never reported how they ended are asked about again at each synchronisation, and the scheduled synchronisation picks up anything else a webhook missed.

Moving work with development events

A workflow trigger is a rule on a transition: when a branch is created, a commit arrives, a merge or pull request is opened, merged or declined, a build passes or fails, or the work is deployed, the work item walks that arrow. It never invents a status change: if the item does not stand where the arrow starts, nothing moves. Automation rules can also react to development events.