PERMISSION/PROTOCOL

Documentation.

Install the GitHub App, wire approvals into your repo workflow, and keep merge paths closed until authority is proven.

Docs overview

Approval gates for pull requests, deploys, and high-impact automation.

These docs cover repository setup, the review lifecycle, status-check enforcement, and the SDK primitives used to gate sensitive actions.

On this page

Getting StartedHow It WorksConfigurationSDK ReferenceFAQ

Getting Started.

Start with GitHub App installation and repository enablement before layering in policy and status checks.

Install the GitHub App

Connect Permission Protocol to your organization so deploy and merge requests can become reviewable authorization events.

Enable it on repositories

Choose the repositories that need deploy gating, receipts, and policy-backed approval flows before changes land.

How It Works.

The approval loop stays explicit from pull request creation through final merge eligibility.

01

PR opened

A pull request includes a change that can trigger a deploy, release, or merge action.

02

Deploy request created

Permission Protocol records the attempted action and creates a review request tied to the PR context.

03

Human reviews

An authorized reviewer checks the request, actor, policy, and target environment before deciding.

04

Approve or reject

Approval issues an authority receipt. Rejection fail-closes the action and preserves the audit trail.

05

Merge or block

Branch protection and required checks ensure unapproved changes cannot merge or deploy downstream.

Configuration.

Enforce the gate with GitHub protections so a rejected or missing approval keeps the change from moving forward.

Recommended setup

Protect your default and release branches in GitHub.

Require the Permission Protocol status check before merge.

Restrict who can bypass branch protection and who can approve requests.

Map repositories and environments to the right approval policy.

Branch Protection Checklist
Repository: billing-service
Protected branch: main
Required status checks:
  - permission-protocol/approval
  - ci/test
Restrictions:
  - Require pull request reviews
  - Restrict force pushes
  - Limit bypass to release admins

SDK Reference.

The core primitives stay small: request authority before action, then require it at execution time.

`authorize()`

Use `authorize()` when your application needs an explicit receipt before deploy, merge, payment, or another irreversible action.

TypeScript
import { authorize } from "permission-protocol";

const receipt = await authorize({
  action: "deploy",
  resource: "billing-service:production",
  context: {
    pull_request: 184,
    commit_sha: process.env.GITHUB_SHA,
  },
});

if (!receipt.verified) {
  throw new Error("Approval required before deploy");
}

`@require_approval`

Use the decorator when you want protected functions to fail closed unless a valid approval receipt is present.

Python
from permission_protocol import require_approval

@require_approval(action="merge", resource="repo/main")
def merge_pull_request(pr_number: int) -> None:
    github.merge_pull_request(pr_number)

@require_approval(action="deploy", resource="billing-service:prod")
def deploy_release(version: str) -> None:
    deploy(version)

FAQ.

Common setup and operations questions for teams deploying Permission Protocol in GitHub-based workflows.

Do I need to change my CI pipeline?

Usually only enough to enforce the Permission Protocol status check and surface approval state before merge or deploy.

Can approvals be environment-specific?

Yes. Teams typically require stricter review for production than for preview or staging environments.

What happens when a request is rejected?

The action remains blocked, the PR cannot satisfy the protected status check, and the rejection is retained in the audit trail.

Are receipts stored with pull request history?

Receipts can be linked to the originating PR and deployment request so reviewers can see who approved what and when.

Can policy engines approve requests automatically?

Yes. A human reviewer, a policy engine, or a hybrid workflow can authorize actions as long as the resulting decision is recorded.

Does this replace GitHub branch protection?

No. Permission Protocol complements branch protection by turning approval into a verifiable authorization event with receipts.

Contact SupportDeveloper Quickstart