GitHub Integration

REAEGIS connects to GitHub using a GitHub App installation. The App listens for push and pull request events, triggers RAMPART evaluations, and allows the ARE to create sandbox branches and pull requests for remediation.

How the GitHub App Works

The REAEGIS GitHub App is installed at the organization level and authorized for specific repositories. When a webhook event is received:

1. REAEGIS verifies the webhook signature (HMAC-SHA256 using GITHUB_WEBHOOK_SECRET)
2. The event is normalized and ingested
3. RAMPART is triggered for push and pull_request events
4. CHRONICLE logs the receipt of the event with a cryptographic signature

The GitHub App uses a private key for authentication (GITHUB_APP_PRIVATE_KEY). This key is used to generate short-lived installation tokens — never sent to clients.

Installing the GitHub App

Webhook Events

REAEGIS processes the following GitHub webhook events:

Required GitHub Permissions

The GitHub App requests these permissions:

What RAMPART Fetches

For each evaluation, RAMPART reads:

• Repository tarball at the evaluated commit SHA
• All Dockerfile, docker-compose.yml, and *.tf files (for IaC gates)
• All dependency manifests (package.json, go.mod, requirements.txt, Cargo.toml, etc.)
• CODEOWNERS file (for branch policy gate)
• Existing SBOM and provenance attestations (from OCI registry)

ARE Sandbox Branch Creation

When the ARE runs a remediation job, it:

1. Downloads the repository at the base branch commit
2. Applies the generated patch
3. Creates a sandbox branch named reaegis/remediate/{job-number} on GitHub
4. Builds and verifies on the sandbox branch
5. Opens a PR from the sandbox branch to the base branch

The sandbox branch is never pushed to production. After CCB approval, the ARE opens two PRs:

• Compliance vault PR: Internal PR for evidence archival
• Customer PR: PR to the customer's staging or main branch with the fix

Dual-PR Routing

Every approved remediation creates two pull requests:

This separation ensures that remediation evidence is preserved regardless of whether the customer merges the implementation PR.

Branch policy compliance

The BRANCH_POLICY RAMPART gate checks your GitHub repository configuration as part of each evaluation. For the gate to pass, the protected branch must have:

Setting up CODEOWNERS:

# .github/CODEOWNERS
# All files require review from the security team
* @your-org/security-team

# Infrastructure files require additional review
*.tf @your-org/infrastructure-team
Dockerfile @your-org/infrastructure-team

The CODEOWNERS file must be present for the BRANCH_POLICY gate to pass. An empty CODEOWNERS file still passes; the gate checks for file presence, not coverage.

Multi-repository programs

A single REAEGIS program can have multiple repositories in scope. Each repository receives its own evaluations, and findings from all repositories contribute to the program's posture score.

Connecting multiple repositories:

1. Install the GitHub App with access to all repositories in scope
2. In REAEGIS, navigate to Settings → Integrations → Source Control
3. For each repository, click Add repository and select it from the list

Each repository connection is stored as a separate SCM configuration. RAMPART evaluates each repository independently on push.

Monorepo considerations:

For monorepos, RAMPART evaluates the entire repository on every push. The SBOM, vulnerability, and IaC gates analyze the full repository tree. If your monorepo contains multiple build systems, RAMPART auto-detects all of them.

Connecting other SCM providers

REAEGIS supports GitHub, Azure DevOps, GitLab, and Bitbucket through the multi-SCM adapter layer. Each provider uses the same evaluation pipeline — the adapter normalizes webhook events into the common RAMPART ingestion format.

For non-GitHub providers, see the individual integration guide in this section.

Security model

Token scope: The GitHub App generates short-lived installation tokens (1-hour expiry) on demand. No long-lived tokens are stored. Tokens are scoped to the specific repositories selected during installation.

Webhook verification: Every webhook is verified using HMAC-SHA256 before processing. Webhooks with invalid signatures are rejected with HTTP 401.

Repository access: REAEGIS only downloads repository content during evaluations — it does not maintain a persistent clone. Each evaluation fetches the tarball at the specific commit SHA, uses it for scanning, and discards it.

Write access isolation: Contents: Write permission is only used by the ARE to create sandbox branches named reaegis/remediate/{job-number}. No other write operations are performed on customer repositories.

Compliance considerations

The GitHub integration satisfies several NIST SP 800-53 requirements:

Troubleshooting

Evaluation not triggering after push

• Verify the GitHub App is installed for the repository (GitHub → Settings → Integrations → GitHub Apps)
• Check that the webhook is active in GitHub → Settings → Webhooks
• Verify GITHUB_WEBHOOK_SECRET matches what is configured in GitHub
• Check REAEGIS event logs: Settings → Integrations → Event log

ARE cannot create branches

• GitHub App requires Contents: Write permission
• Check the App installation's repository permissions in GitHub → Settings → Integrations → GitHub Apps
• Ensure the App is authorized for the specific repository, not just the organization

Webhook signature validation fails

• The GITHUB_WEBHOOK_SECRET in REAEGIS must exactly match the secret configured in the GitHub webhook
• Do not regenerate the webhook secret without updating it in REAEGIS — this breaks all webhook delivery
• Secrets must match exactly, including trailing whitespace

SBOM_ATTESTATION gate always WARN

• SBOM attestations must be attached to the OCI image in the registry, not just generated as files
• Use cosign attest --type cyclonedx to attach the SBOM to the image after build
• REAEGIS verifies the attestation against the image digest from the IMAGE_DIGEST gate

GitHub App expired private key

• GitHub App private keys do not expire unless revoked
• If installations return 401 errors, the private key may have been rotated in GitHub
• Regenerate the private key in GitHub → Settings → Developer settings → GitHub Apps, then update GITHUB_APP_PRIVATE_KEY in REAEGIS

Related pages

• RAMPART Engine — What RAMPART does with each push event
• ARE Engine — How the ARE uses GitHub to create remediation PRs