GitHub and GitLab

Linking commits, branches and pull requests to tickets.

When an administrator has connected a code host, commits, branches and pull requests that mention a ticket key are linked to the ticket automatically. Mention the key anywhere: in a commit message, a branch name, or a pull request title or description.

Connecting a code host

An administrator adds the integration under Administration, Integrations: choose GitHub or GitLab, give it a name and, for a self-managed host, its base URL. Saving shows the webhook URL and a secret once, and lists the settings to enter on the code host, which are also here. The URL is the workspace's public address, which the code host must be able to reach. The integration page counts deliveries so you can tell the webhook is working.

On GitHub

In the repository, or the organisation to cover every repository in it, open Settings, Webhooks, Add webhook:

  1. Payload URL: the webhook URL.
  2. Content type: application/json. The form-encoded choice is not read.
  3. Secret: the secret shown once when the integration was created. Every delivery is checked against it.
  4. SSL verification: leave it enabled when the URL is https.
  5. Under Which events would you like to trigger this webhook? choose Let me select individual events and tick Pushes, Branch or tag creation, Branch or tag deletion and Pull requests; leave everything else unticked. Just the push event misses branches and pull requests.
  6. Leave Active ticked and press Add webhook. GitHub sends a ping at once; a 202 under Recent Deliveries means the URL and secret are right.

On GitLab

In the project, open Settings, Webhooks, Add new webhook:

  1. URL: the webhook URL.
  2. Secret token: the secret shown once when the integration was created.
  3. Trigger: tick Push events (all branches) and Merge request events; leave the others unticked. GitLab always posts JSON, so there is no content type to choose.
  4. SSL verification: leave it enabled when the URL is https.
  5. Press Add webhook, then Test, Push events on the webhook's page; a 202 in the response means the URL and secret are right.

Connecting an account of your own cannot be tried in the public demo workspace, whose logins are everybody's: see In the demo.

The Development panel

A ticket with linked activity shows a Development panel listing each commit, branch and pull request with its state (open, merged, closed), the repository and branch, and the author. Everything links back to the code host. The history records when each link was made.

Commands in commit messages

Commit messages can act on the ticket they mention:

  • #comment followed by text adds that text as a comment, with a link to the commit.
  • # followed by a transition name runs that transition, for example #start-progress or #resolve. Case, spaces and dashes do not matter. A transition that needs a resolution gets Done or Fixed.

Commands run as you, matched by the email address or username on the commit, so you must be an Alba user with permission on the project. Otherwise the link is still made and the command is ignored.

An administrator can also choose a transition to run whenever a pull request that mentions a ticket is merged.