GitHub Checks roadmap

GitHub Checks Production Plan

Planning only - real GitHub Check Runs are not created yet.

GitHub Check Preview exists today; real GitHub Check Runs are planned but not live.

Keep the current GitHub Check Preview stable in private beta, then design dry-run check payloads after workspace/auth/RLS boundaries and audit events are ready.

Review Runs First repo setup Production architecture Readiness

Safeguards

Required before real Check Runs

Explicit environment flag such as GITHUB_CHECK_RUNS_ENABLED=true before real checks can be created.
Workspace-level allowance before any repository can receive real Check Runs.
Approved repository must be selected and tied to the GitHub App installation identity.
Installation identity must match the workspace repository record.
Idempotency key should prevent duplicate Check Runs for the same review_run and commit SHA.
Audit event must be written before and after any real Check Run create/update attempt.
Kill switch must disable Check Runs immediately without redeploying risky behavior.
No auto-merge behavior is introduced by Check Runs.
Generic Platform Guidance: Human approval remains required for manual-review, blocked, failed, protected-path, and sensitive-path cases.
Do not expose raw diffs, raw repo rules, tokens, private keys, webhook payloads, or provider errors in Check Run output.

Current boundary

What is not happening yet

No GitHub Checks API calls.
No real GitHub Check Runs are created or updated.
No GitHub posting is enabled by this plan.
No auto-merge, live agents, autonomous workflows, billing, or production persistence.

Staged roadmap

From preview-only to controlled production checks

stage_1_preview_only

Preview-only model

current

ForgeLayer derives GitHub-style check status locally and displays it in Review Runs without calling GitHub Checks APIs.

Entry criteria: GitHub Check Preview exists, Review Run Status Lifecycle exists, PR Comment Preview v2 remains safe
Blocked until: No blocker for preview-only mode

stage_2_workspace_gated_beta

Workspace-gated beta design

planned

Design per-workspace and per-repository allowances for future real Check Runs.

Entry criteria: Production workspace identity adapter is active and verified, RLS behavior is integration-tested, approved repositories are workspace-scoped
Blocked until: workspace auth, RLS, audit event model

stage_3_dry_run_check_payloads

Dry-run check payloads

planned

Generate the exact GitHub Check Run payload server-side while still not sending it to GitHub.

Entry criteria: idempotency key format decided, check name/body length limits tested, safe annotations policy exists
Blocked until: workspace allowance, audit event writes, kill switch

stage_4_controlled_check_runs

Controlled Check Runs

future_blocked

Create or update one ForgeLayer Check Run only for approved workspace repositories when explicitly enabled.

Entry criteria: Checks: write permission approved, installation identity verified, repository approved, audit event written
Blocked until: explicit env flag, workspace allowlist, idempotency, human approval gate

stage_5_production_rollout

Production rollout

future_blocked

Enable Check Runs for production workspaces with clear controls, audit logs, and rollback/kill-switch procedures.

Entry criteria: beta checks stable, support runbook exists, tenant controls tested, security review complete
Blocked until: production auth, billing/plan boundaries if needed, operational monitoring

Future permissions

Least-privilege permission plan

metadata

read

current

GitHub App installation and repository identity checks.

Metadata read is expected for GitHub App basics.

contents

read

current

Fetching repo-owned forgelayer.yml policy.

Already used for RepoBrain repo rules fetch.

pull_requests

read

current

Reading PR metadata and review context.

Write should remain future-only unless needed for controlled PR review actions.

checks

write

future

Creating or updating real GitHub Check Runs.

Do not request or rely on Checks: write until workspace gates, audit events, idempotency, and kill switch are ready.

pull_requests

write

future

Only if future PR review submission requires it.

Not required for preview-only Check Runs planning.

Mapping plan

Review status to GitHub check result

completed

success

non-blocking

completed + LOW risk + merge recommendation

Human review: not required
Notes: Matches the current low-risk Check Preview success mapping.

completed

action_required

non-blocking

needs_manual_review or medium/high risk requiring human review

Human review: required
Notes: Signals that a human gate is required before merge.

completed

failure

blocks merge

failed, blocked, hard block, unsafe high risk, or provider-safe error

Human review: required
Notes: Blocks merge until the review can be regenerated or blocking findings are resolved.

queued

neutral

non-blocking

queued

Human review: not required
Notes: Check is waiting for processing.

in_progress

neutral

non-blocking

received or processing

Human review: not required
Notes: Check is actively processing or the queue foundation has received the job.