GitHub Integration

Rack Gateway integrates with GitHub to verify commits and (optionally) post PR comments when deploy approval requests are created.

Features

• Commit verification against a branch
• PR detection for the branch being deployed
• Optional PR comments when a request is created
• Branch policy controls (no deploys from the default branch unless allowed)

Configuration

Gateway Environment Variable

# GitHub personal access token or app installation token
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Token Permissions

The gateway reads the branch, compares commits, lists open pull requests and (optionally) comments on one:

Permission	Access	Purpose
Contents	Read	Read the branch and compare commits
Pull requests	Read (write to comment)	Find the branch’s open PR, and post the PR comment

Fine-grained token

1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Limit it to the repositories you deploy, with Contents (read) and Pull requests (read and write)
3. Store it as GITHUB_TOKEN

Classic token

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate a token with the repo scope (public_repo is enough for public repositories)
3. Store it as GITHUB_TOKEN

The gateway reads GITHUB_TOKEN once at startup. An app installation token expires after an hour, so use a long-lived token.

Per-App Settings

These settings live under Apps → {app} → Settings:

Setting	Description	Default
vcs_provider	github	github
vcs_repo	Repository in owner/repo format, e.g. MyOrg/myapp	none
github_verification	Enable commit verification	true
verify_git_commit_mode	branch or latest	latest
require_pr_for_branch	Require an open PR	true
default_branch	Default branch name	main
allow_deploy_from_default_branch	Allow deploys from default branch	false
github_post_pr_comment	Post PR comment on request creation	true

github_verification is on by default, and it fails closed: while it’s on, the gateway refuses to create deploy approval requests for the app unless GITHUB_TOKEN and the app’s vcs_repo are both set. Set them, or turn github_verification off for apps that don’t deploy from GitHub.

# Environment variable configuration
RGW_APP_MYAPP_SETTING_VCS_PROVIDER=github
RGW_APP_MYAPP_SETTING_VCS_REPO=MyOrg/myapp
RGW_APP_MYAPP_SETTING_GITHUB_VERIFICATION=true
RGW_APP_MYAPP_SETTING_VERIFY_GIT_COMMIT_MODE=latest
RGW_APP_MYAPP_SETTING_REQUIRE_PR_FOR_BRANCH=true
RGW_APP_MYAPP_SETTING_DEFAULT_BRANCH=main
RGW_APP_MYAPP_SETTING_ALLOW_DEPLOY_FROM_DEFAULT_BRANCH=false
RGW_APP_MYAPP_SETTING_GITHUB_POST_PR_COMMENT=true

Commit Verification

When a deploy approval request is created with github_verification on, the gateway checks, in order:

1. The request names a branch (--branch); without one it’s refused with git_branch is required for GitHub verification
2. The branch isn’t default_branch or the repository’s default branch on GitHub, unless allow_deploy_from_default_branch is on: otherwise it’s refused with deploying from default branch 'main' is not allowed. By default, deploys come from a feature branch
3. The commit matches the branch, by verify_git_commit_mode:
   • latest: commit must equal the branch head
   • branch: commit must be the branch head or one of its ancestors
4. With require_pr_for_branch on, the branch has an open pull request

A request that repeats an open one (same app, commit and target token) is answered 409 with that request before any of these checks, so it doesn’t call GitHub. Each user can create DEPLOY_APPROVAL_LIMIT_BURST requests (default 20), themselves or with any of their API tokens, before they’re refused with 429, and gets DEPLOY_APPROVAL_LIMIT_PER_HOUR (default 60) back each hour.

If any check fails, the gateway answers 400 (for example GitHub verification failed: no open pull request found for branch my-branch) and no request is created.

Pull Request Detection

When GitHub verification is enabled, the gateway attempts to find an open PR for the branch. If found, the PR URL is stored with the request as pr_url. The request’s page in the web UI links it, the Slack notification links it, and rack-gateway deploy-approval show (and approve and wait, before approving) prints it as PR:. deploy-approval show -o json and deploy-approval list -o json include pr_url.

Audit Trail

The deploy_approval_request.create audit entry records the verification as change-management evidence: github_verification is passed, or skipped (with github_verification_skip_reason) when verification is off for the app. A passed check also records the vcs_repo, verify_git_commit_mode and require_pr_for_branch it used, and the pr_url it found. See Audit Trail.

The gateway also logs one info line per passed verification, with the app, repo, branch, commit, mode and PR.

PR Comments

If github_post_pr_comment is enabled, the gateway posts a comment when the request is created. The comment includes a link to the approval request.

Note

PR comments are only posted on request creation (not on approval/rejection).

Troubleshooting

• Ensure GITHUB_TOKEN is set and has access to the repo
• Verify vcs_repo matches owner/repo
• A refused request’s error says which check failed. A failed GitHub check is also logged as a gateway warning with the app, repo, branch and commit.