Skip to content
Docs

GitHub and GitLab

When your code lives on GitHub or GitLab, Orbit can show it on the work items it belongs to. That covers branches, commits, pull requests, builds, deployments and security alerts. This page is for site administrators who connect a provider and for people who read the results. In development

Code hosted in Forge links to work items through Forge itself and needs no connection. See Merge requests and approvals.

How it works

Section titled “How it works”

The provider sends webhooks to Orbit. Orbit never calls the provider back, stores no provider token and does not backfill history. If a delivery is missed, recover it by redelivering from the provider, and use the repair queue for keys that did not match.

Only site administrators connect providers. The routes need a signed-in session.

Connect a provider

Section titled “Connect a provider”
  1. Create an integration with POST /admin/dev-integrations on https://acme.orbit.inortix.com/api/v1. Give it a provider of github or gitlab and a name of 1 to 200 characters. Optionally add projectIds (up to 100, none means all) and smartCommits.
  2. Copy the secret, which starts with owdv_, and the url. Orbit shows the secret once.
  3. In the provider, add a webhook that posts to the url with the secret.

A site can have 50 integrations. Providers post without signing in to Orbit, up to 1 MiB each, and Orbit checks the signature.

Provider Signature
GitHub X-Hub-Signature-256: sha256=<hex HMAC-SHA256 of the raw body>
GitLab X-Gitlab-Token with the secret

A wrong signature answers 401 dev_signature_invalid. A turned-off integration answers 403 dev_integration_disabled. A delivery id is kept, so the same delivery again changes nothing, and one that failed is applied when it is sent again.

To rotate the secret, call POST /admin/dev-integrations/{id}/secret with overlapHours from 0 to 168 (the default is 24). The old secret works until previousSecretValidUntil.

What becomes an item

Section titled “What becomes an item”
Provider event Item
GitHub push, create and delete of a branch branch and commit
GitHub pull_request, GitLab Merge Request Hook pull_request: open, draft, merged or declined
GitHub workflow_run, GitLab Pipeline Hook build: pending, running, success, failed or cancelled
GitHub deployment_status, GitLab Deployment Hook deployment: pending, running, success, failed, cancelled or inactive
GitHub security alerts, GitLab Vulnerability Hook vulnerability: open, fixed or dismissed

GitLab Push Hook produces branches and commits. Other events are recorded as ignored. A later report updates an item in place, and an older report never sets it back.

Section titled “How items link to work items”

An item links to the work items whose keys appear in its commit message or title in upper case. It also links to keys in its branch name, in any case. An item links to at most 20 keys. Old keys after a move or a project key rename still work. A build, deployment or request also links to the work of the commit (by SHA, a short SHA included) or branch it ran on.

A key of a project that exists or existed but names no work item goes to a repair queue. Orbit retries it every few minutes and on request. Administrators can link such an item to a work item by key or dismiss it.

See the results

Section titled “See the results”
  • Work item. GET /issues/{id}/development-items lists the newest 200 items with a summary of branches, commits, pull requests, builds and deployments.
  • Project. GET /projects/{id}/development?days=30 (1 to 90 days) shows connected repositories, open pull requests, the last build and deployments per environment. It also shows deployments per week, change failure rate, the median lead time from commit to successful deployment, and recent failures. Everyone who can read the project sees vulnerability counts. Only project administrators see the alert details.
  • Version. GET /versions/{id}/development shows, per environment, which work items of the version have been deployed. It also lists up to 200 work items that no environment has.
  • Delivery log. GET /admin/dev-integrations/{id}/deliveries lists the latest 100 deliveries of the last 30 days as processed, ignored or failed.

Automation rules can start on development events such as a new branch, a merged pull request, or a failed build or deployment. See Automation rules.

Smart commits In development

Section titled “Smart commits ”

With smartCommits on, a line in a pushed commit message that names work item keys and then commands acts on those work items.

Commit message
OPS-12 OPS-13 #comment Fixed the rounding #time 1h 30m Pairing #in-progress
Command Effect
#comment Adds the text up to the next command as a comment
#time Logs time in w, d, h and m (a day is 8 hours, a week 5 days, at most 31 days) from the commit time, and lowers a remaining estimate
Any other #word Moves the work item through the one transition from its status whose target status or name matches the word, ignoring spaces, hyphens and case. Transitions that ask for screen fields are not used.

A commit can have 10 commands. A worker runs them in order as the Orbit person whose e-mail is the commit author’s, with that person’s permissions at that moment. A refused command fails with its reason, and other failures are retried up to 8 times. A commit reported again runs nothing again. Request titles and build messages never run commands.

Anyone who can push can write a commit in someone else’s name. Turn smart commits on only where the people who push are trusted.

Section titled “Related”