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]

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:

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

Token Placement

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]

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.

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

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 dispatches the same workflow again and records run-bound accepted-risk metadata on the blocked result comment or pull request review.
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 requests, the acceptance is also bound to the current head SHA. A changed head requires a fresh acceptance.

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.