How Vergate's GitHub integration works — and why it's privacy-respecting by design

Every SaaS product claims to "integrate with GitHub." Far fewer can explain what happens the moment you click Install. This post is the honest technical breakdown of how Vergate's GitHub integration actually works — the event flow, the cryptographic guarantees, and the deliberate privacy choices we made.

#The architecture: GitHub App, not OAuth token

The first and most important design decision: Vergate connects via a GitHub App, not a classic OAuth personal token.

With an OAuth token, a tool gets access to everything your token can reach — and the token is a long-lived credential that sits in a database somewhere, usable until it's revoked. With a GitHub App, the model is inverted:

• You choose the repos. When you install the GitHub App, you pick exactly which repositories it can access.
• Credentials are short-lived and per-installation. GitHub mints an installation token on demand; Vergate never stores a reusable password for your account.
• Scope is minimal by construction. The app requests only the permissions it actually uses: reading workflow files, reading metadata, and writing Check Runs.

#The event flow, step by step

Here's what happens when your developer pushes a commit:

1. Push event. GitHub sends a push webhook to POST /api/v1/webhooks/github with headers including the delivery ID and the HMAC signature.
2. Signature verification. We verify the payload with HMAC-SHA256 against a shared webhook secret. No valid signature → the request is rejected before any processing. Payloads are also checked against the delivery ID and event type, and we ignore event types we don't handle.
3. Installation resolution. We resolve the installation ID from the payload, map it to the org's stored installation, and mint a fresh, short-lived installation JWT to call GitHub's API back.
4. Project lookup. We match the repository's full name (owner/repo) against your Vergate projects. If the repo isn't linked to a project, we skip the scan — we never guess.
5. Workflow analysis. We fetch the GitHub Actions workflow files at that exact commit (HEAD SHA from the push payload) and run them through the analyzer: hardcoded secrets, unpinned actions (uses: action@v3 instead of a pinned SHA — a supply-chain risk), over-broad workflow permissions, dangerous patterns (curl | bash, secret exfiltration, disabled security gates), and missing checks like required approvals.
6. Check Run. We create (or update) a GitHub Check Run named vergate/security-scan on that commit, with inline annotations on the exact lines that triggered findings. Your CI panel shows it right next to your build checks — "Vergate security scan: 2 warnings, 1 critical" — with conclusions that mark the run failure or success.

Pull requests follow the same path, with the PR number and head SHA attached so the Check Run appears directly in the PR's check list — an extra gate your team can require before merge, no separate dashboard login required.

#What we scan — and deliberately don't

We analyze GitHub Actions workflow files (.github/workflows/*.yml): CI/CD configuration, not application code. The five check families:

1. Hardcoded secrets — API keys, tokens, or passwords written directly into workflow files. We redact detected secrets in reports so they never leak into logs or Check Run annotations.
2. Unpinned actions — uses: some-action@v1 or @main floats, which silently change behavior when the upstream tag moves. Pinning to a full commit SHA is the supply-chain-safe practice.
3. Excessive permissions — workflows granted contents: write or id-token: write when they only need read access. Principle of least privilege, applied to CI.
4. Dangerous patterns — curl | bash escalation, secrets patched into base64-encoded form, SECRETS written to environment variables that downstream steps can echo out.
5. Missing security gates — no branch protection, no required status checks, auto-merge enabled without review.

What we don't do: we don't clone your repository, we don't scan application source code, we don't read issues or pull request bodies, and we don't store your workflow files beyond the scan artifacts you can see in the results page.

#Privacy guarantees, concretely

• Webhook signatures: every event verified with HMAC-SHA256 before processing.
• Short-lived tokens: installation JWTs expire; there is no long-lived credential for us to lose.
• Repo-level consent: you pick the repositories. Unlisted repos never trigger a scan.
• No code storage: workflow YAML is analyzed in memory; only the findings (file, line, severity, remediation) are persisted.
• Diff tracking: every scan compares against the previous one, so you see new findings vs. resolved findings — with an email alert if a critical/high finding appears.

#The boring security detail that matters: Check Runs need permission

One subtlety worth calling out: creating Check Runs requires the app to have the checks: write permission, and it only works on repos where you installed the app. If you see a Vercel-style "ghost" check that never completes, it's usually one of: the app not installed on that repo, the workflow path not matching, or the repo not linked to a Vergate project.

#Why it's worth installing

CI/CD is where your secrets live, where your deployments run, and where a compromised pipeline does the most damage — yet it's the part of most repositories with the least security scrutiny. Vergate's GitHub integration puts a security review of your pipelines directly into the developer workflow, on every push and every PR, with zero extra steps for your team.

Set it up once: install the GitHub App → link a repository → push a commit. From then on, every PR carries a Vergate security check that your team can require before merge.