feat: deployment approval UI and backend handlers by Flo4604 · Pull Request #5256 · unkeyed/unkey

Flo4604 · 2026-03-09T09:20:39Z

What does this PR do?

Adds GitHub Check Runs support for deployment authorization workflow. When external contributors push to protected branches, the system now creates visible check runs in GitHub PRs that require project member authorization before deployments can proceed.

The implementation includes:

GitHub Check Run API integration with create, update, and list operations
Automatic check run creation for unauthorized deployments from external contributors
Check run status updates to "success" when deployments are authorized by project members
New web UI page for authorizing deployments with approve/dismiss actions
Configuration support for GitHub App ID and private key credentials
Audit logging for deployment authorization events

When testing:::

Please ensure your app has the following permissions(this is important for prod too)!!

then go into https://github.com/settings/installations and find your app and re-approve the perms.

For testing the happy path: FORCE_DEPLOYMENT_APPROVAL should be set to false in the yaml file.

Fixes # (issue)

Type of change

Bug fix (non-breaking change which fixes an issue)
Chore (refactoring code, technical debt, workflow improvements)
Enhancement (small improvements)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update

How should this be tested?

Create a PR from an external contributor to a protected branch
Verify a GitHub check run appears with "action_required" status
Navigate to the authorization page and approve the deployment
Confirm the check run updates to "success" status
Test the dismiss functionality and verify check run remains failed
Verify audit logs are created for authorization events

Checklist

Required

Appreciated

If a UI change was made: Added a screen recording or screenshots to this PR
Updated the Unkey Docs if changes were necessary

vercel · 2026-03-09T09:20:44Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dashboard	Ready	Preview, Comment	Mar 16, 2026 11:55am

Flo4604 · 2026-03-09T09:20:53Z

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

feat: deployment approval UI and backend handlers #5256 👈 (View in Graphite)
feat: gate deployments from non-collaborators behind approval #5255 : 1 other dependent PR (#5295 )
feat: report deployment status to GitHub Deployments API #5254
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

coderabbitai · 2026-03-09T09:21:05Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: d8a374f0-b90e-4d63-84f1-6b8af96651e3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feat/deployment-approval-ui

📝 Coding Plan

Generate coding plan for human review comments

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Add the complete approval/rejection flow for gated deployments: Backend (ctrl service): - Add ApproveDeployment and RejectDeployment RPCs to DeployService proto - Implement approve handler: validates status, updates to pending, records approval, triggers deploy workflow via Restate - Implement reject handler: validates status, updates to failed - Add FindAppBuildSettingByAppEnv SQL query for approval flow Dashboard: - Add awaiting_approval to deployment status badges, filters, and collection - Add DeploymentApprovalBanner component with approve/reject buttons - Show banner on deployment detail page when awaiting approval - Add tRPC mutations for approve/reject calling ctrl service - Add deployment.approve and deployment.reject audit log events

- Add 'rejected' to deployment status badges, filters, and collections - Add DeploymentRejectedBanner with red error styling - Show rejected banner on deployment detail page - Add rejected to grouped status filter with error color

Remove deployment approval/rejection banners, status badge configs, filter options, and tRPC routes for awaiting_approval/rejected statuses. Add /projects/[projectId]/authorize page that reads branch from URL params and calls AuthorizeDeployment RPC. Add authorize tRPC route.

The ctrl API needs GitHub App credentials to fetch branch HEAD when authorizing deployments from external contributors.

- Remove awaiting_approval and rejected from deployment statuses, filters, and status badge configs (no longer used — authorization is handled via GitHub Check Runs, not deployment status) - Remove deployment.approve and deployment.reject audit log events - Delete unused duplicate deployment-status-badge.tsx in table components - Fix broken page.tsx referencing undefined awaitingApproval/rejected vars - Extract createCtrlClient helper to deduplicate identical ctrl client creation boilerplate across 9 trpc router files

Centered layout with GitHub + shield icons, commit details card showing branch/SHA/message/sender from URL query params, proper Button components, success/error states, and non-member handling hint.

…backs

Frontend now validates SHA format (40-char hex) before allowing authorization and passes it to the backend which verifies it matches the branch HEAD.

Instead of a generic error, show a clear message explaining the branch has new commits and direct the user to GitHub to find the latest authorization link.

Instead of telling the user to check GitHub, parse the new HEAD SHA from the backend error and offer a direct "View Latest Commit" button that navigates to the updated authorize page.

…om DB - Rewrite authorize page to take single deploymentId search param - Fetch deployment details from DB via getById instead of URL params - Handle awaiting_approval, already authorized, and failed states - Simplify authorize mutation input to just deploymentId - Add gitCommitMessage, gitCommitAuthorHandle, gitCommitAuthorAvatarUrl, projectId to getById response - Register getById in tRPC router

Replace the separate /authorize page with an inline DeploymentApproval component shown when deployment status is awaiting_approval. Delete the standalone authorize page. Add awaiting_approval to deriveStatusFromSteps valid statuses so it doesn't fall back to pending.

Flo4604 mentioned this pull request Mar 9, 2026

feat: report deployment status to GitHub Deployments API #5254

Merged

14 tasks

Flo4604 mentioned this pull request Mar 9, 2026

feat: gate deployments from non-collaborators behind approval #5255

Draft

14 tasks

vercel bot deployed to Preview March 9, 2026 09:23 View deployment

Flo4604 force-pushed the feat/deployment-approval-ui branch from d315940 to cc70395 Compare March 9, 2026 13:42

Flo4604 force-pushed the feat/external-contributor-protection branch from 36216f3 to 66dad62 Compare March 9, 2026 13:42

vercel bot deployed to Preview March 9, 2026 13:44 View deployment

Flo4604 force-pushed the feat/deployment-approval-ui branch from cc70395 to 5eeb2b0 Compare March 10, 2026 08:34

Flo4604 force-pushed the feat/external-contributor-protection branch from 66dad62 to 4f7c6e8 Compare March 10, 2026 08:34

vercel bot had a problem deploying to Preview March 10, 2026 08:36 Failure

Flo4604 force-pushed the feat/external-contributor-protection branch from 4f7c6e8 to 24ccc92 Compare March 10, 2026 09:11

Flo4604 force-pushed the feat/deployment-approval-ui branch from 5eeb2b0 to 990e123 Compare March 10, 2026 09:11

vercel bot had a problem deploying to Preview March 10, 2026 09:13 Failure

Flo4604 force-pushed the feat/external-contributor-protection branch from 24ccc92 to fc52cb0 Compare March 10, 2026 14:13

Flo4604 force-pushed the feat/deployment-approval-ui branch from 990e123 to 9edfbae Compare March 10, 2026 14:13

vercel bot deployed to Preview March 10, 2026 14:15 View deployment

Flo4604 force-pushed the feat/deployment-approval-ui branch from 9edfbae to d034877 Compare March 10, 2026 17:58

Flo4604 force-pushed the feat/external-contributor-protection branch from fc52cb0 to 4fea8a6 Compare March 10, 2026 17:58

vercel bot deployed to Preview March 10, 2026 18:01 View deployment

Flo4604 force-pushed the feat/deployment-approval-ui branch from d034877 to 60772bf Compare March 11, 2026 16:14

Flo4604 force-pushed the feat/external-contributor-protection branch from 4fea8a6 to 0edf2ec Compare March 11, 2026 16:14

vercel bot deployed to Preview March 11, 2026 16:16 View deployment

Flo4604 force-pushed the feat/deployment-approval-ui branch from 60772bf to 6a191d7 Compare March 11, 2026 18:02

Flo4604 force-pushed the feat/external-contributor-protection branch from 0edf2ec to be84e80 Compare March 11, 2026 18:02

vercel bot deployed to Preview March 11, 2026 18:04 View deployment

Flo4604 force-pushed the feat/deployment-approval-ui branch from 6a191d7 to a808725 Compare March 11, 2026 18:21

vercel bot deployed to Preview March 11, 2026 18:24 View deployment

Flo4604 force-pushed the feat/deployment-approval-ui branch from a808725 to adf6636 Compare March 12, 2026 07:32

vercel bot deployed to Preview March 12, 2026 14:26 View deployment

Flo4604 force-pushed the feat/deployment-approval-ui branch from ec39be3 to de084e0 Compare March 12, 2026 14:31

vercel bot deployed to Preview March 12, 2026 14:33 View deployment

vercel bot deployed to Preview March 12, 2026 14:36 View deployment

Flo4604 force-pushed the feat/external-contributor-protection branch from 653be32 to 37d6876 Compare March 12, 2026 14:59

Flo4604 force-pushed the feat/deployment-approval-ui branch from 228d914 to 1f59d61 Compare March 12, 2026 14:59

Flo4604 mentioned this pull request Mar 12, 2026

feat: add Vercel-style PR comment for deployment status #5295

Draft

19 tasks

Flo4604 force-pushed the feat/external-contributor-protection branch from 37d6876 to 64f8baa Compare March 12, 2026 17:14

chronark approved these changes Mar 16, 2026

View reviewed changes

Flo4604 and others added 21 commits March 16, 2026 12:52

feat: add rejected status to dashboard UI

ab97c1d

- Add 'rejected' to deployment status badges, filters, and collections - Add DeploymentRejectedBanner with red error styling - Show rejected banner on deployment detail page - Add rejected to grouped status filter with error color

fix: use correct Loading import from @unkey/ui

54d5590

fix: pass through actual error message from ctrl service

80ed920

fix: add GitHub App credentials to ctrl-api config

4e2211b

The ctrl API needs GitHub App credentials to fetch branch HEAD when authorizing deployments from external contributors.

feat: redesign deployment authorization page

a94ee15

Centered layout with GitHub + shield icons, commit details card showing branch/SHA/message/sender from URL query params, proper Button components, success/error states, and non-member handling hint.

feat: link branch, commit SHA, and sender to GitHub on authorize page

061d803

refactor: use nuqs for authorize page search params, remove null fall…

fc1f20e

…backs

fix: pass commit SHA through authorization flow and validate on frontend

6756175

Frontend now validates SHA format (40-char hex) before allowing authorization and passes it to the backend which verifies it matches the branch HEAD.

feat: show dedicated stale commit UI when branch has moved

46736e3

Instead of a generic error, show a clear message explaining the branch has new commits and direct the user to GitHub to find the latest authorization link.

feat: redirect to latest commit authorization when stale

e54dd6c

Instead of telling the user to check GitHub, parse the new HEAD SHA from the backend error and offer a direct "View Latest Commit" button that navigates to the updated authorize page.

fix: reset mutation state before navigating to latest commit

a345b25

fix: resolve TypeScript null check on authorize.error

6ff1925

fix: use optional chain instead of non-null assertion for biome lint

0ad529b

[autofix.ci] apply automated fixes

537bb3f

fix: replace dots with X icon in authorization connection indicator

36c456c

[autofix.ci] apply automated fixes

36a3aed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: deployment approval UI and backend handlers#5256

feat: deployment approval UI and backend handlers#5256
Flo4604 merged 21 commits intofeat/external-contributor-protectionfrom
feat/deployment-approval-ui

Flo4604 commented Mar 9, 2026 •

edited

Loading

Uh oh!

vercel bot commented Mar 9, 2026 •

edited

Loading

Uh oh!

Flo4604 commented Mar 9, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Mar 9, 2026 •

edited

Loading

Review skipped

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Flo4604 commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Type of change

How should this be tested?

Checklist

Required

Appreciated

Uh oh!

vercel bot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Flo4604 commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Flo4604 commented Mar 9, 2026 •

edited

Loading

vercel bot commented Mar 9, 2026 •

edited

Loading

Flo4604 commented Mar 9, 2026 •

edited

Loading

coderabbitai bot commented Mar 9, 2026 •

edited

Loading