Connect GitHub

The GitHub connector reads a selected repository and its workflow run metadata. It does not change source, dispatch workflows, deploy applications or connect to customer databases.

Prepare the credential

Create a GitHub App installation token or fine-grained token with access to the intended repository only. It needs repository Metadata and Contents read access; add Actions read access when importing workflow results. Store the credential in a server secret named BUILDVOUCH_GITHUB_TOKEN_<NAME>.

Short-lived installation tokens must be refreshed by the operator's secret-management process. BuildVouch does not issue a GitHub App private key or rotate upstream credentials.

Bind an application

The server setting BUILDVOUCH_GITHUB_BINDINGS maps a BuildVouch application UUID to one repository and credential name. A customer owner cannot substitute another organisation's repository through a browser field.

{
  "APPLICATION_UUID": {
    "repository": "YOUR_ORG/YOUR_REPOSITORY",
    "token_env": "BUILDVOUCH_GITHUB_TOKEN_PILOT",
    "checks": [
      {
        "control_key": "build",
        "workflow_path": ".github/workflows/verify.yml",
        "environment": "ci",
        "events": ["push"]
      }
    ]
  }
}

Replace placeholders with verified identifiers. The server also needs SUPABASE_SERVICE_ROLE_KEY to write verified source records; this key must never use a VITE_ prefix or appear in browser code.

Verify the workflow meaning

A workflow mapping is a trust decision. Review the workflow and its permissions before mapping it to a control. Map a workflow to tenant isolation only when that workflow actually runs the required deterministic isolation tests. A successful workflow is evidence of its declared work, not an independent security certification.

Sync

An owner or editor opens the application and chooses Sync GitHub. BuildVouch fetches the current default-branch commit and up to 100 recent runs for that SHA. It accepts only the configured workflow path, environment and event, with matching head repository and branch. Fork and pull_request_target results are not eligible.

Pending, skipped and neutral runs do not count as passed. A newer failed or pending run supersedes an earlier success. Repeated syncs deduplicate source records by run, attempt, state and control.

Understand the environment

The binding labels evidence with its explicitly configured environment. A ci record does not satisfy a production requirement. Configure checks against the environment they actually test.

Limits and recovery

Sync requests are limited to six per application per minute. A failed request leaves prior source records intact. A renamed repository, expired credential or missing binding requires operator review. The connector does not follow redirects to another host.