Deploy Gate Demo

As AI becomes capable of writing and shipping code autonomously, we need guardrails that keep humans in the loop — not as a formality, but as genuine decision-makers. This demo shows how: a checkpoint that forces reviewers to engage with changes before signing a cryptographic attestation. The attestation proves not just that someone clicked approve, but that they confirmed understanding of the problem, objective, and tradeoffs.

The full protocol goes further: domain-specific gates tailored to context, verified identity, integration with deployment systems and AI-assisted review that helps humans understand complex changes — not bypass them. The goal is twofold: prevent gradual loss of direction as systems scale, and provide clear, attributable authorization in high-risk or regulated environments where decisions must be explicit and defensible.

Live Demo: demo.humanagencyprotocol.org

GitHub: github.com/humanagencyprotocol/hap-deploy-gate-demo

How It Works

This demo implements a human checkpoint for code deployment. Before any PR can be merged, a human must review the changes and create a cryptographic attestation proving they made an informed decision.

The Flow

┌─────────────────────────────────────────────────────────────────────────┐
│  1. DEVELOPER creates PR                                                │
│     └─→ GitHub Action runs → ❌ Blocks merge (no attestation)          │
└─────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────┐
│  2. REVIEWER opens attestation UI and progresses through 6 gates:       │
│                                                                         │
│     Gate 1: Frame                                                       │
│       • Load PR (title, description, changed files)                     │
│       • Select execution path: Canary or Full                           │
│                                                                         │
│     Gate 2: Decision Owner                                              │
│       • Select and lock role (Engineering / Release Management)         │
│                                                                         │
│     Gate 3: Problem                                                     │
│       • Articulate in your own words: what problem does this solve?     │
│                                                                         │
│     Gate 4: Objective                                                   │
│       • Articulate in your own words: what outcome are you approving?   │
│                                                                         │
│     Gate 5: Tradeoffs                                                   │
│       • Articulate: what risks are you accepting under this path/role?  │
│                                                                         │
│     Gate 6: Commitment                                                  │
│       • Review summary and sign attestation                             │
└─────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────┐
│  3. SERVICE PROVIDER signs attestation                                  │
│     • Computes frame hash (repo + SHA + env + path)                     │
│     • Records which gates were passed                                   │
│     • Signs with Ed25519 key                                            │
│     • Returns cryptographic blob with 1-hour TTL                        │
└─────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────┐
│  4. REVIEWER posts attestation as PR comment                            │
│     └─→ GitHub Action re-runs → Verifies signature → ✅ Allows merge   │
└─────────────────────────────────────────────────────────────────────────┘

Navigation

The UI features a persistent navigation bar showing:

• AI Assistant link (left) - Configure optional AI assistance
• 6 Gate pills - Visual progress through the attestation flow

Gates can be revisited and edited after completion. Changes are held in draft state until explicitly saved.

What Gets Verified

The GitHub Action checks:

• ✓ Attestation exists for the current commit SHA
• ✓ Cryptographic signature is valid
• ✓ Attestation hasn’t expired
• ✓ All required roles have attested (Engineering for Canary, Engineering + Release Management for Full)

AI Assistant (Advisory Boundary)

This demo includes an optional AI assistant to help reviewers understand changes before approving. The AI can answer questions, summarize diffs, and surface potential issues — but it has no authority in the decision process.

AI configuration is available from the AI Assistant link in the navigation bar. You can change settings at any time during the review.

AI Options

1. Local/Private AI (Recommended) — Run AI locally with Ollama. Your data never leaves your machine. This is the trusted option.

2. Public AI (Demo only) — Use OpenAI, Groq, or other cloud providers. Warning: Do not use with sensitive or confidential data. PR content will be sent to external servers.

3. No AI — Review changes without AI assistance.

What AI Can Do

• Answer questions about the changes
• Summarize diffs and highlight affected areas
• Point out potential risks or contradictions
• Help reviewers think through tradeoffs

What AI Cannot Do

• Write or modify decision fields
• Select tradeoffs or execution paths
• Close gates or trigger attestations
• Influence what gets executed

The Boundary

All AI output remains local and is never included in the signed attestation. The system records what was approved — not the AI’s reasoning or the reviewer’s intent.

Approval is always a human act, based on explicit structural commitments.

Structure

demo/
├── apps/
│   ├── ui/           # Attestation UI (Next.js, localhost:3000)
│   └── server/       # Service Provider (Next.js, localhost:3001)
├── packages/
│   └── hap-core/     # Shared canonicalization and verification logic
└── .github/
    └── workflows/
        └── hap-check.yml  # GitHub Actions attestation verification

Quick Start

Option A: Use the Public Server (Recommended)

A public Service Provider is available at https://service.humanagencyprotocol.org — no server setup required.

# Install dependencies
pnpm install

# Build shared package
pnpm --filter @hap-demo/core build

# Start UI only
pnpm dev:ui

Create apps/ui/.env.local:

GITHUB_TOKEN=<your personal access token with repo scope>
NEXT_PUBLIC_SP_URL=https://service.humanagencyprotocol.org

Option B: Run Your Own Server

# Install dependencies
pnpm install

# Build shared package
pnpm --filter @hap-demo/core build

# Start server (SP)
pnpm dev:server

# Start UI (separate terminal)
pnpm dev:ui

Create apps/ui/.env.local:

GITHUB_TOKEN=<your personal access token with repo scope>
NEXT_PUBLIC_SP_URL=http://localhost:3001

GitHub Setup

Enable Branch Protection (Required for Merge Gate)

To block merges without valid attestations, you need to set up a branch ruleset:

1. Go to Settings → Rules → Rulesets → New ruleset → New branch ruleset
2. Configure the ruleset:
   • Ruleset name: HAP Protection
   • Enforcement status: Active
3. Under Target branches, click Add target → Include by pattern:
   • Enter: main
4. Under Branch rules, enable:
   • Require status checks to pass
     • Click Add checks and search for: Verify HAP Attestation
   • Require a pull request before merging (recommended)
   • Block force pushes (recommended)
5. Click Create

Without this setup, the workflow will report status but won’t block merges.

Note: The GitHub Action automatically uses https://service.humanagencyprotocol.org for attestation verification. No additional configuration is needed.

Demo Flow

Single Approval (Canary Path)

1. Create a PR to the main branch
2. Run pnpm dev:ui (or also pnpm dev:server if running locally)
3. Open http://localhost:3000
4. Configure AI Assistant (optional) or click Continue to skip
5. Gate 1 - Frame: Enter the PR URL, click “Load PR”, select Canary path, close gate
6. Gate 2 - Decision Owner: Select Engineering role, lock role and close gate
7. Gate 3 - Problem: Write what problem this change addresses (20-240 chars), close gate
8. Gate 4 - Objective: Write what outcome you’re approving (20-240 chars), close gate
9. Gate 5 - Tradeoffs: Write what risks you accept as Engineering under Canary, close gate
10. Gate 6 - Commitment: Review summary and click “Sign Attestation”
11. Click “Post to PR Comment” to add the attestation to the PR
12. The GitHub Action will verify the attestation and allow merge

Multi-Person Approval (Full Path)

For production deployments requiring multiple approvals:

1. Create a PR and in Gate 1, select Full (immediate deployment) path
2. Engineer goes through all 6 gates:
   • Gate 2: Select role Engineering
   • Gates 3-5: Articulate problem, objective, and tradeoffs
   • Gate 6: Sign and post attestation to PR
3. Release Manager goes through the UI separately:
   • Gate 2: Select role Release Management
   • Gates 3-5: Articulate from their perspective
   • Gate 6: Sign and post as another PR comment
4. GitHub Action verifies both attestations are present and valid
5. Merge is allowed only when all required roles have attested

Endpoints

Service Provider (SP)

• GET /api/sp/pubkey - Get SP public key
• POST /api/sp/attest - Request attestation
• POST /api/sp/verify - Verify attestation signature

Attestation UI

• GET / - Attestation wizard
• POST /api/attest - Request attestation (proxies to SP)
• POST /api/comment - Post attestation to PR
• GET /api/comments - Fetch PR comments

Environment Variables

Server

SP_PRIVATE_KEY=<hex>     # Ed25519 private key (optional, generates ephemeral if not set)
SP_PUBLIC_KEY=<hex>      # Ed25519 public key

UI

GITHUB_TOKEN=<token>     # For posting/reading PR comments
NEXT_PUBLIC_SP_URL=http://localhost:3001

Protocol Compliance

This demo implements:

• Deploy Gate Profile v0.2 - Frame canonicalization, Decision Owner scopes
• Attestation format - Ed25519 signatures, TTL enforcement
• Multi-person approval - Role-based attestations aggregated by workflow
• Cryptographic verification - Signature verification via deployed service
• Error codes - INVALID_SIGNATURE, EXPIRED, FRAME_MISMATCH, etc.

See Human Agency Protocol for full specification.