GitHub Integration

Require signed human approval for GitHub pull request merges and deployments using the SignedApproval GitHub App.

Key Concepts

The SignedApproval GitHub App installs on your repositories and creates commit status checks on pull requests. When a PR targets a protected branch, SignedApproval creates an approval request. The status check remains "pending" until a human approves (or rejects) via the dashboard or iOS app. Once approved, the commit status turns green and the PR can be merged.

Unlike GitHub's built-in review approvals, SignedApproval's checks produce a cryptographic Ed25519 signature — unforgeable proof that a specific human authenticated and approved at a specific time.

Setup Guide

Install the GitHub App

Visit github.com/apps/signedapproval and click Install. Choose which repositories to install on — you can select all repositories or specific ones.

Connect in the dashboard

After installation, you'll be redirected back to SignedApproval. Log in to your dashboard and go to Settings → Integrations → GitHub. The app installation will be automatically detected.

Configure repository settings

For each repository, configure:

Branch patterns — Which branches require approval (e.g., main, release/*).
Auto-merge — Whether to auto-merge the PR after approval (optional).
Quorum — How many approvals are needed (default: 1).

Enable branch protection on GitHub

The SignedApproval check appears on every PR automatically, but won't block merges until you make it required. This is a one-time step per repo:

Go to your repo → Settings → Branches
Under Branch protection rules, click Add rule (or edit the existing rule for main)
Check “Require status checks to pass before merging”
In the search box, type SignedApproval and select it from the results
Check “Require a pull request before merging”
Set “Required approvals” to 0 (the SignedApproval status check is your merge gate, not GitHub reviews)
Optionally check “Do not allow bypassing the above settings” so even admins can't skip it
Click Save changes

Direct link: github.com/<owner>/<repo>/settings/branches

Important

Do notset “Required approvals” to 1 or higher. The SignedApproval GitHub App submits PR reviews when you approve, but GitHub does not count App bot reviews as “reviewers with write access” — this is a GitHub platform limitation. Use the required status check as your merge gate instead. It provides stronger security: GitHub reviews are a button click, while SignedApproval requires biometric authentication and produces an Ed25519-signed cryptographic proof.

How It Works

A developer opens a PR targeting a protected branch (e.g., main).
The GitHub App receives a webhook and creates a "pending" commit status check.
An approval request is created in SignedApproval, notifying the configured approver.
The approver reviews the PR details, authenticates, and approves or rejects.
The commit status is updated to "success" (approved) or "failure" (rejected).
If auto-merge is enabled and the PR has all required checks, GitHub merges automatically.

Webhook Events

The GitHub App listens for these webhook events:

pull_request.opened — Creates the approval request when a PR is opened.
pull_request.synchronize — Updates the status check when new commits are pushed.
pull_request.closed — Cleans up the approval request if the PR is closed without merging.

Webhook payloads are verified using the GITHUB_WEBHOOK_SECRET.

Note

The GitHub App (ID: 3164945) is available at github.com/apps/signedapproval. It requests only the minimum permissions needed: commit statuses (read/write) and pull requests (read).

Tip

Combine GitHub branch protection with SignedApproval status checks for defense-in-depth. Even if someone bypasses GitHub's review requirements, they cannot forge the Ed25519 signature that SignedApproval produces.

Bitbucket Integration GitLab Integration How Approvals Work