GitHub integration

Available on: Team and above for connecting, plans from tags and check runs. Business and Enterprise for the deployment protection rule. On lower plans the rule answers rejected with the comment "Requires Business plan" (fail closed, because it is a gate). After a downgrade, connections are kept but gated features stop being processed. See pricing.

The Deployment Playbook GitHub App connects a workspace to your GitHub organization:

• Tag or release → plan. Pushing a tag (or publishing a release) that matches a pattern in a mapped repository creates a plan from the mapped template. One plan per repository + tag; redeliveries and re-pushes don't create duplicates.
• Check run on the tagged commit. A "Deployment Playbook" check run links to the plan and is updated on every change: in progress while sign-off runs, success when the plan is done, failure when it's rejected, cancelled when it's rolled back.
• Deployment protection rule. Enable the app on a GitHub environment and deployment jobs to that environment wait until the plan's gate phase is open (the same rule as the gate API). Then the app approves the deployment. A rejected plan, or a deployment with no matching plan, is rejected.

No long-lived GitHub credentials are stored: the app uses short-lived installation tokens (valid 1 hour), created on demand with the app's private key.

Connect a workspace

You need the Admin role in the workspace and permission to install apps on the GitHub organization.

1. Open Integrations in the workspace menu and click Install the GitHub App.
2. On GitHub, pick the organization and the repositories the app may access, then confirm.
3. GitHub asks you to authorize the app once. This lets us check that your GitHub account can access the installation, so no one can link someone else's installation. You're sent back to Integrations.
4. Under Repository → template, add a mapping:
   • Repository: owner/repo.
   • Template: the template new plans use.
   • Environment: the environment name shown on the plan.
   • Tag pattern: * is a wildcard. The default is v*.
   • Gate phase: deployments may start once this phase is open. DURING means the plan is approved and every BEFORE step is resolved.
   • Four-eyes: whether plans created from this mapping require four-eyes approval.

Plans are created on behalf of the Admin who installed the app, and the audit log records them as created "via github integration".

Protect a GitHub environment

1. In the repository, open Settings → Environments → production (or another environment).
2. Under Deployment protection rules, enable Deployment Playbook and save.
3. In your workflow, deploy with environment: production from a tag:

on:
  push:
    tags: ["v*"]
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production   # waits for Deployment Playbook
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh

When the job starts, GitHub asks the app. The app looks up the plan by repository and commit (or tag), and answers as soon as the gate phase opens. The job waits on GitHub (environment protection rules can wait up to 30 days).

Permissions requested

Permission	Access	Why
Checks	Read & write	Create and update the check run on the tagged commit
Deployments	Read & write	Approve or reject deployments waiting on the protection rule
Actions	Read	Required by GitHub for deployment protection rules
Contents	Read	Resolve a release's tag to its commit
Metadata	Read	Mandatory for every app

Events: push, release, deployment_protection_rule (plus installation, which every app receives).

Security

• Webhooks are verified with HMAC-SHA256 (X-Hub-Signature-256), de-duplicated by X-GitHub-Delivery, and rate-limited per installation.
• Deployment callbacks are only sent to api.github.com. The callback URL is stored encrypted (AES-256-GCM).
• Outbound calls go only to api.github.com and github.com. See Security & network.
• Disconnect on the Integrations page removes the link and its mappings. Uninstall the app on GitHub (Settings → GitHub Apps) to revoke its access entirely. When the app is uninstalled, the integration is disabled automatically.

Troubleshooting

• No plan appears. Check that the repository name matches the mapping exactly, that the tag matches the pattern, and that the app has access to the repository. The Integrations page shows the last error.
• Deployment rejected with "No Deployment Playbook plan found". The deployment's commit or tag has no plan. Push a mapped tag first, or create the plan with POST /api/plans using the same repository and tag.
• GitHub Enterprise Server isn't supported yet.