ChangeBoxChangeBox
Become a design partner

07

GitHub App

Install the ChangeBox GitHub App on the repositories agents work in. ChangeBox hears about merges, CI and deployments, can merge a pull request the moment the Ship gate is approved, and can hold a GitHub deployment until the gate is decided. Nothing ships without a decision recorded in ChangeBox.

  • pull_request

    Head SHA on open and push; merge recorded, and live when the environment's signal is merge

  • check_suite · workflow_run · status

    CI state on the current head; green re-evaluates autonomous shipping

  • deployment_status

    Release recorded; live when the environment's signal is deploy

  • deployment_protection_rule

    GitHub asks before deploying; ChangeBox answers from the Ship gate

Connecting

Settings → Code → GitHub → Connect GitHub sends an owner or admin to GitHub to install the app on the account and pick repositories. GitHub brings them back and the installation is bound to the workspace. Add repositories later from GitHub's installation settings; ChangeBox follows along. The app's primary repository must be in the installation for merges and deployment holds to work on it.

Self-hosting? The deployment needs GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_PRIVATE_KEY and GITHUB_WEBHOOK_SECRET, a webhook at /api/github/webhook and a setup URL at /api/github/setup. Permissions: pull requests read and write, checks read, deployments read and write, contents read and write, metadata read. Until they are set, Setup says the app is not configured and people mark changes live by hand.

Live signals

Each environment says what makes a change live there. Deployment: GitHub reports a successful deployment to that environment — the default, and the honest one when a pipeline deploys. Give the environment its GitHub name if it differs. Merge: the pull request merging counts, for repos that deploy on merge with no deployment record. Manual: someone marks it live. Whatever the signal, the Ship gate must already be approved; a deployment that lands first is recorded as waiting, and the reporter is not asked to check until the gate is decided.

Merge on ship approval

Turn it on per app in Setup → App. When the Ship gate is approved — in the console, the widget, Slack, email or by policy — ChangeBox squash-merges the pull request through the app, with the approver and channel in the commit message. The merge is only attempted on the head ChangeBox last saw; a push after approval refuses the merge and says so on the timeline.

Deployment protection

In a GitHub environment's protection rules, add the ChangeBox app as a required reviewer. Deployments to that environment then wait for ChangeBox. If the commit belongs to a change whose Ship gate is approved, the deployment is released at once; if the gate is open, it is held and released the moment someone approves; if rejected, the deployment is rejected with the note. Commits with no ChangeBox change are approved as not gated so your pipeline is never stuck on us.

Autonomous shipping

On an app whose execution policy is autonomous, policy may approve the Ship gate itself, but only when every piece of evidence is green: low risk in the spec, no security flags, CI passed on the current head, the independent review of the current PR came back clean, and no blocker findings are open. Anything missing holds the gate for a person. Every evaluation is stored with its reasons, and a policy-approved ship is flagged in the evidence packet for retrospective review. With merge on ship approval and a deployment signal, a low-risk report can go from widget to live with no one clicking anything — and a complete record of why that was allowed.