GitHub Connection Security
GitHub Connection Security
Section titled “GitHub Connection Security”Reference for answering customer questions about how PulseStream accesses their GitHub repositories.
The short version
Section titled “The short version”PulseStream uses a GitHub App — the same integration model used by Vercel, CircleCI, and Codecov. The customer installs the App on their GitHub org, picks which repos to share, and that’s it. We never store any GitHub tokens or credentials. When we need to read code, we generate a short-lived token on the fly that expires in 1 hour.
How the connection works
Section titled “How the connection works”- Customer clicks Connect GitHub in PulseStream settings
- They’re redirected to GitHub, where they install the PulseStream App and select repos
- GitHub sends us an installation ID — a reference number that says “this org trusts this App”
- We store that installation ID and the repo list. Nothing else.
When PulseStream needs to access code (for AI analysis):
- Our Control Plane signs a JWT with PulseStream’s App private key (10-min TTL)
- Exchanges that JWT with GitHub’s API for an installation access token (1-hour TTL)
- Passes the token to the Analysis Engine to clone the repo
- Token expires and is never saved
The customer never sees or manages these tokens.
What we store vs. what we don’t
Section titled “What we store vs. what we don’t”| We store | We never store |
|---|---|
| Installation ID (a reference number) | GitHub access tokens (ghs_...) |
| GitHub org/user name | OAuth tokens or refresh tokens |
| Repo list (name, clone URL, branch) | Personal access tokens |
| Installation status (active/suspended) | Any customer GitHub credentials |
Permissions
Section titled “Permissions”The App requests only:
- Contents — read-only
- Metadata — read-only
We cannot write to code, manage org settings, access webhooks, or see anything outside the repos the customer selected.
Security controls
Section titled “Security controls”Credential protection
Section titled “Credential protection”- App private key is PulseStream’s own signing key (not a customer credential). Encrypted at rest with AWS KMS, stored in Kubernetes Secrets via SOPS. Not in the database.
- Webhook secret for HMAC-SHA256 verification on all inbound GitHub events. Verification is mandatory — webhooks are rejected if the secret isn’t configured (fail-closed).
Access controls
Section titled “Access controls”- Token minting requires authentication — either a user JWT with workspace membership, or a workspace API key for backend services
- Both token endpoints are IP-rate-limited (20/min user-facing, 30/min internal)
Audit trail
Section titled “Audit trail”- Every token mint is logged to the audit table with: who requested it, which workspace, which installation, client IP, and timestamp
- Event type:
github.token_minted - GitHub also independently logs all App token activity, visible to the customer’s org admins
Environment isolation
Section titled “Environment isolation”Each PulseStream environment (dev, demo, staging, prod) has its own separate GitHub App with its own credentials. A compromise of one environment’s key cannot affect another.
Customer controls
Section titled “Customer controls”- Repo selection: Customer chooses exactly which repos the App can access during installation
- Instant revocation: Uninstalling the App from GitHub org settings immediately and permanently cuts all PulseStream access. No tokens to revoke, no cleanup needed.
- GitHub audit log: All App activity is logged on GitHub’s side, visible to org admins
Common customer questions
Section titled “Common customer questions””Do you store our GitHub token?”
Section titled “”Do you store our GitHub token?””No. We never store any GitHub tokens. We store only the installation ID — a reference number. When we need to access code, we generate a short-lived token on demand that expires in 1 hour and is never saved.
”What if PulseStream gets breached?”
Section titled “”What if PulseStream gets breached?””An attacker with full Control Plane access could mint installation tokens for connected orgs, scoped to the read-only permissions. Mitigations:
- Tokens are short-lived (1 hour) — blast radius is time-bounded once the breach is contained
- Every token mint is audit-logged on our side
- Rate limiting prevents bulk token generation
- Customer can uninstall the App instantly to cut access
- GitHub’s audit logs provide independent visibility the customer controls
This is the same trust model as every GitHub App integration (Vercel, CircleCI, Codecov, etc.).
”Can PulseStream modify our code?”
Section titled “”Can PulseStream modify our code?””No. The App only has read-only permissions (Contents + Metadata). We cannot push commits, create branches, modify settings, or write anything.
”Can you access repos we didn’t select?”
Section titled “”Can you access repos we didn’t select?””No. GitHub enforces repo selection at the installation level. We can only see repos the customer explicitly granted access to.
”How do we disconnect?”
Section titled “”How do we disconnect?””Go to GitHub org settings → Installed GitHub Apps → PulseStream → Uninstall. Access is cut immediately. On PulseStream’s side, the installation is marked as deleted via webhook, and no further tokens can be minted.
”Do you have your own credentials, or do you use ours?”
Section titled “”Do you have your own credentials, or do you use ours?””We use our own. PulseStream has an RSA private key that identifies our App to GitHub. That key is ours, encrypted with AWS KMS. We never have or need your GitHub credentials.