Security and Permissions

Security And Permissions

GitVibe keeps authority in GitHub. AI can recommend and produce structured results, but trusted humans control approval, protected labels, review, and merge decisions.

Security Boundaries

flowchart TD
  A[GitHub webhook] --> B[Verify HMAC signature]
  B --> C[Check repository actor permission]
  C --> D{Trusted action?}
  D -->|no| E[Reject command or remove protected label]
  D -->|yes| F[Dispatch workflow or update GitHub state]
  F --> G[AI stage returns JSON]
  G --> H[Schema validation]
  H --> I[Deterministic write code]
  I --> J[Human review and merge]

Loading

Rules:

• Webhook bodies must pass x-hub-signature-256 verification.
• Commands and protected labels require write, maintain, or admin.
• gvi: labels are internal runtime labels.
• AI output must validate against a stage schema before writes.
• GitVibe reviews existing PRs, but does not open, update, approve, or merge PRs.
• Current GitVibe workflows do not push branches, commit code, open pull requests, or remediate PR feedback.
• Web safety rules are prompt guidance, not a hard network boundary. Use runner or network egress controls for strict web isolation.

GitHub App Permissions

Hosted GitVibe uses a GitHub App private key to mint short-lived installation tokens. Customer repositories do not create a GITVIBE_GITHUB_TOKEN PAT.

The registered App needs these repository permissions:

Permission	Access	Required for
Actions	Read and write	Workflow dispatch and workflow run lookup
Checks	Read-only	Verifying GitHub Actions OIDC jobs before token minting
Contents	Read and write	Repository content access for the hosted app server profile
Discussions	Read and write	Optional Discussion-backed feature workflows
Issues	Read and write	Issues, comments, assignees, labels, and milestones
Pull requests	Read and write	Pull requests, comments, labels, and review workflows
Secrets	Read and write	Legacy Codex auth writeback for older pinned workflows
Variables	Read-only	Reading repository workflow dispatch settings

The app server does not hand out that full permission set to runners. It uses scoped token profiles:

Profile	Scope
server	Webhook orchestration and dispatch config
runner-read	Read-only runner stages and matrix members
runner-status-write	Comments, labels, and stage status writes
runner-workflow-write	Review matrix dispatch
server-checks-read	OIDC check-run verification
server-secrets-write	Legacy Codex auth writeback

server-secrets-write is retained for compatibility with older pinned workflows that still call /actions/codex-auth. Current Codex SDK profiles use proxy base_url and api_key bundle fields instead.

Token Placement

Token or secret	Store in	Never store in
GITVIBE_APP_PRIVATE_KEY	Hosted app operator runtime env or deploy secret	Consumer repositories, .github/git-vibe.yml, comments, logs
GITVIBE_AI_ENV_JSON	Repository or organization secret	Repository files
GITHUB_WEBHOOK_SECRET	Hosted app operator runtime env	Repository files
WEBHOOK_SECRET	Hosted app deploy workflow secret	Repository files

Runner logging redacts values from GITVIBE_AI_ENV_JSON and sensitive environment variable names. Do not rely on redaction as a substitute for narrow tokens.

Trusted Actor Model

flowchart LR
  Actor[Webhook sender] --> API[GET collaborator permission]
  API --> Perm{permission or role_name}
  Perm -->|admin, maintain, write| Trusted[Trusted]
  Perm -->|read, triage, none, missing| Untrusted[Untrusted]

Loading

Trusted actors can:

• Run supported /git-vibe commands.
• Add public trigger labels.
• Request pull request review automation with git-vibe:review.
• Approve GitVibe pull requests in GitHub.

Untrusted actors can still report bugs, participate in Discussions, and leave PR feedback. They cannot start write automation.

SDK Adapter Risk

codex-sdk and claude-code-sdk run non-interactive AI stages with permission bypass appropriate for GitVibe's deterministic runner. Use them only on dedicated Linux or macOS runners with:

• Hosted GitHub App token exchange instead of long-lived repository PATs.
• No unnecessary host mounts.
• No unrelated secrets.
• Controlled network and filesystem access appropriate for the repository.

GitVibe prompts SDK adapters to treat web access as read-only research and avoid forms, uploads, state-changing requests, and suspicious downloads. That prompt is not a substitute for runner-level egress controls.

Removed local proxy, Agentool, and direct CLI adapters are migrated by git-vibe-setup update where possible, but runtime execution supports only SDK profiles. Windows runners are not supported.

Prompt-Injection Gate

GitVibe runs an AI prompt-injection classifier before AI execution and before publishing stage output when safety.prompt_injection_gate is enabled or omitted in .github/git-vibe.yml. Set that field to false only when the repository owner accepts skipping both input and output prompt-injection scans.

The classifier uses the same configured stage or matrix-member AI profile routing described in AI and Stage Contracts. Codex classifier runs use a read-only sandbox.

Pull Request Review Snapshot Boundary

Automatic review uses pull_request_target, so GitVibe keeps trusted action code and repository configuration on the base checkout. The security job reads the event head SHA when available, verifies it against the current PR, selects the latest usable completed GitVibe checkpoint, and freezes the resulting file snapshot. The checkpoint and snapshot values are internal job outputs, not consumer-controlled action inputs.

Matrix members receive a separate checkout of the contributor repository at the frozen target SHA. GitVibe verifies that checkout's HEAD, restricts review members to read-only repository inspection, disables model MCP servers for review members, and disables Codex web and network access. Configuration, profiles, role definitions, prompts, and deterministic GitHub write code still come from the trusted base and workflow revision.

The security job's input-safety attestation is reusable only for byte-equivalent normalized context. A changed diff, comment, review thread, or other context unit produces a different digest and triggers another safety scan. Before reconciling threads, publishing a review, or advancing labels, GitVibe verifies that the PR still points to the frozen target. New reviews are also submitted with GitHub's commit_id field set to that target SHA.

safety.ignored_authors adds GitHub logins whose comment and review timeline items are omitted from prompt-injection scans and model context. CodeRabbit (coderabbitai and coderabbitai[bot]) is ignored by default. Keep this list narrow: ignored bot findings may still be useful, but GitVibe will depend on its own review for those cases.

Protected Label Policy

GitHub does not protect labels natively. GitVibe enforces policy in webhook handling:

sequenceDiagram
  participant User
  participant GitHub
  participant App as GitVibe app

  User->>GitHub: Add git-vibe:* or gvi:* label
  GitHub->>App: labeled webhook
  App->>GitHub: Check actor permission
  alt unauthorized
    App->>GitHub: Remove label
    App->>GitHub: Post audit comment
  else authorized trigger label
    App->>GitHub: Dispatch workflow
  else internal runtime label
    App->>GitHub: Accept only managed runtime state
  end

Loading

For label names and effects, see Commands and Labels.

Accepted Risk Label

git-vibe:accept-risk is the maintainer escape hatch for a blocked prompt-injection input risk. It does not disable safety scanning globally.

When a trusted maintainer applies the label to an artifact with a blocked GitVibe result:

1. The app finds the latest trusted blocked stage result for that artifact.
2. It replaces that blocked result comment or pull request review with a compact accepted-risk result that stores hidden accepted-risk metadata.
3. The security-review job for that run treats context before the acceptance cutoff as accepted risk and scans context created or edited after the cutoff.
4. If the post-cutoff delta is safe, GitVibe removes git-vibe:accept-risk and downstream jobs continue.
5. For pull request reviews, a later push can reuse the same acceptance only while the PR title/body hash still matches. GitVibe still scans the current PR file diff, new timeline items, and handoffs after the accepted cutoff.

For blocked pull request reviews, GitVibe reruns review.yml, removes stale PR review state, and applies gvi:reviewing while the accepted-risk review is running. If GitHub cannot return a workflow run id or GitVibe cannot record run-bound metadata, the app removes git-vibe:accept-risk and posts an audit comment instead of treating the label itself as authority.

The downstream review-matrix synthesizer does not need the security-review blocked result as input. After accepted-risk metadata has been consumed, GitVibe filters that metadata source out of prompt context and does not reblock on already accepted pull request context during synthesis. Role definitions, MCP prompt additions, and new post-cutoff context are still scanned.