Connecting GitHub to Landfall
Connect a GitHub organization so Beacon, the investigator agent, can search code, read commits and pull requests, and trace an incident back to the specific change that caused it — not just the infrastructure it broke. GitHub can also open a Landfall war room directly, from a security or deploy-failure signal; see Triggering Integrations → GitHub.
One GitHub App, not a key you paste in
Every other Landfall integration asks you to create your own API key or webhook. GitHub works differently: Landfall registers one GitHub App, and your organization installs it — the same way you'd install any other GitHub App, choosing exactly which repositories it can see. There is no secret to generate, copy, or rotate on your side; GitHub itself issues short-lived, revocable tokens to Landfall behind the scenes, scoped only to the repositories you selected.
You stay in control the whole time: uninstalling the App, or narrowing its repository access, from your GitHub organization's settings takes effect immediately — Landfall never holds a credential that outlives that decision.
What you'll need
- Owner or admin access on the GitHub organization you want to connect.
- Your Landfall organization's slug — it appears in your Landfall URL, e.g. /o/acme/….
- An admin on your Landfall organization.
Connect your organization
Settings → Integrations → GitHub → Connect
Landfall mints a short-lived, signed token binding the install flow to your Landfall organization, and sends your browser to GitHub's own install page for the Landfalls Incident Response App.
Choose repository access
GitHub asks which repositories the App can see — all repositories (current and future) or a hand-picked subset. This choice is entirely GitHub's own native install UI; Landfall never sees anything you didn't select.
github.com/organizations/your-org/settings/installations
One click installs — or, as shown here, confirms — the App on your organization. Exactly what access is requested
GitHub shows the permission set before you approve anything. Landfall requests only what the investigator agent and the incident-trigger webhook actually use, all read-only — there is no write scope in the App at all, so there is no code path that could push, merge, or comment even by accident.
github.com/organizations/your-org/settings/apps/landfalls-incident-response
This exact summary — Read access to Dependabot alerts, actions, code, metadata, pull requests, secret scanning alerts, and security events — is what your organization approves. Nothing more. Redirected back, connected
GitHub sends your browser back to Landfall with the installation confirmed. Landfall verifies it live against GitHub's API before marking the connection as configured — an installation that can't actually be reached is refused rather than saved.
The permission set, in detail
Every permission below is Read-only, set once when the App was registered — an installing organization cannot grant more than this even if it wanted to.
| Permission | What it's for |
|---|---|
| Contents: read | Search code, read file contents, list commits, diff a commit or PR, blame a line/file — the investigator agent's core code-browsing tools. |
| Pull requests: read | List and read pull requests, so a finding can link the actual PR that shipped a change. |
| Actions: read | Read workflow runs — correlating a deploy SHA to the commits it shipped, and (optionally) triggering an incident on a deploy-critical workflow failure. |
| Code scanning alerts: read | Optional trigger source — open an incident from a critical code-scanning alert. |
| Dependabot alerts: read | Optional trigger source — open an incident from a critical dependency vulnerability. |
| Secret scanning alerts: read | Optional trigger source — open an incident when a leaked secret is detected. The alert's location/matched-secret fragment is stripped before it ever reaches an incident timeline; see Triggering Integrations → GitHub. |
Enabling code search/browsing does not require enabling security-alert triggering, and vice versa — both ride the same connection, but each is a separate opt-in event type (see triggering docs). A tenant that only wants deploy-correlation without exposing secret-scanning alert data can decline that scope's use entirely by leaving it out of the connection's enabled event types.
Mapping repositories to services
Landfall correlates an alerting service (from Datadog, CloudWatch, or any other connected telemetry source) to a GitHub repository by name. In Settings → Integrations → GitHub, map each service name your telemetry uses to the owner/repo it lives in. An unmapped service falls back to the repository search the agent already has access to — mapping just makes the very first correlation immediate instead of a search.
What the investigator agent can do once connected
The moment a github connection exists, the agent automatically gains it as a new capability — no separate switch, no agent-side code change, the same dynamic discovery every other source uses (see Integrations Architecture):
- Search code across every repository the installation can see.
- Read a file's contents at any commit or branch.
- List recent commits and pull requests for a repository.
- Diff a commit or pull request.
- Blame a line or file to find who (and which PR) last touched it.
- Correlate a deploy marker or SHA to the commits it shipped.
Every result the agent surfaces carries a permalink back to the exact commit, PR, file, and line — a finding is never "somewhere in the repo," it's a link you can open.
Troubleshooting
| Symptom | Cause |
|---|---|
| Agent can't find a repository | It wasn't included in the installation's repository selection. Add it from github.com/organizations/your-org/settings/installations — access updates immediately, no reconnection needed in Landfall. |
| Connection shows disconnected | The App was uninstalled, or its repository access was revoked, on GitHub's side. Reinstall it from Settings → Integrations → GitHub to reconnect. |
| A finding's code link 404s | The branch was force-pushed or the file was deleted after the finding was recorded — the permalink is pinned to the commit SHA at the time, which is intentional (it documents what the agent actually saw), but that commit may no longer be reachable if history was rewritten. |
What Landfall does with the connection
- Reads only. The App has no write scope at all — not a convention, a hard limit enforced by GitHub itself on every token it issues.
- Per-installation tokens, minted on demand. Landfall never stores a long-lived GitHub credential for your organization; it holds only your non-secret installation id and mints a short-lived (about one hour) access token from it when the agent actually needs one.
- Scoped to what you selected. Repository access is enforced by GitHub, not by Landfall's own bookkeeping — the same install-time choice that limits a human collaborator's access limits the agent's.
- Revocable from your side, immediately. Uninstall the App, or narrow its repository access, from your GitHub organization's settings and access ends at once.