Triggering integrations · GitHub

Opening a war room from a GitHub alert or failed deploy

Four kinds of GitHub event can open a Landfall incident: a code scanning alert, a secret scanning alert, a Dependabot alert, and a failed run of a workflow you mark deploy-critical. This page is about opening incidents. Reading code is on Connecting GitHub, and triggering needs that connection first, because both use the same GitHub App.

GitHub

alert or failed run

→

App webhook

signed, X-Hub-Signature-256

→

Landfall

opens an incident

How it works

The Landfalls Incident Response App has one webhook URL and one signing secret, set once by Landfall, so there is no webhook for you to create. GitHub sends the App's events to POST https://api.landfalls.ai/triggers/github, signed with X-Hub-Signature-256. Landfall checks the signature first, then finds your organization from the installation ID in the body.

A bad signature and a valid signature for an installation no Landfall organization holds get the same 401, so the endpoint cannot be used to find out which organizations are connected.

After that, Landfall acts only on the event types you turned on. For an alert, only GitHub's created and reopened actions count. For a workflow run, only a completed run that failed, of a workflow on your deploy-critical list. Everything else gets a 200 and is dropped, so GitHub never retries it. Each alert or run opens at most one incident: a repeat of the same one is recognized and opens nothing.

What you'll need

GitHub connected to your Landfall organization; see Connecting GitHub.
An admin on your Landfall organization, to turn events on and save them.
For the alert events, the GitHub feature that raises the alert turned on for the repository: code scanning, secret scanning or Dependabot alerts.

1. Turn on the events you want

In Landfall, open Integrations → Source control → GitHub. The Incident triggering section has one switch per event, and all four start off, so nothing opens an incident until you turn one on. Turn on the ones you want, then click Save mapping & triggers.

What each event does

Switch in Landfall	GitHub event	What it does
Code scanning alert	code_scanning_alert	Opens an incident for a new or reopened alert. Severity comes from the rule's security severity, or from its severity when there is none.
Secret scanning alert	secret_scanning_alert	Opens an incident for a new or reopened alert, at sev1, because these alerts carry no severity of their own. Landfall keeps the secret type, the repository and a link to the alert, and removes where the secret was found before the event reaches a timeline every room participant can read.
Dependabot alert	dependabot_alert	Opens an incident for a new or reopened alert, with the advisory's severity.
Deploy-critical workflow failure	workflow_run	Opens an incident, at sev2, for a completed run that failed, of a workflow on your deploy-critical list (step 2). Other failed runs open nothing.
None	installation, installation_repositories	Never opens an incident. Each of these events, including repositories added, makes Landfall drop its cached token and record the GitHub connection as failed.
None	Everything else	Answered with a 200 and dropped.

There is no severity threshold: every new or reopened alert of a type you turned on opens an incident. The incident takes its severity from GitHub, with critical as sev1, high or error as sev2, and medium, warning, low, note or any other value as sev3. An alert that carries no severity at all is sev2.

What GitHub's fields become

GitHub field	Becomes
repository.full_name	The start of the title, for example acme-demo/shop: Dependabot alert (high). Also the affected service, unless you mapped the repository to a service name.
workflow_run.name	The title of a workflow incident: acme-demo/shop: deploy-critical workflow "deploy" failed.
alert.created_at, workflow_run.updated_at	When the incident says the problem started.
alert.html_url, workflow_run.html_url	A link back to the alert or run on GitHub, kept on the incident.

2. Mark deploy-critical workflows

A failed Actions run is common and usually not an incident: a flaky test, a lint failure on a draft pull request. So Landfall reacts only to runs of workflows you name. Turn on Deploy-critical workflow failure, and the Deploy-critical workflows list appears under it. Click + Add workflow and enter the owner, the repository and the workflow's full path, for example .github/workflows/deploy.yml. Then click Save mapping & triggers.

Landfall matches all three exactly as GitHub reports them, so a workflow with the same file name in another folder does not count.

3. Test it

The quickest real test is a deploy-critical workflow that fails on purpose. In a repository the App can see, add this file on the default branch, add it to the deploy-critical list in step 2, and run it from the repository's Actions tab.

.github/workflows/landfall-test.yml

name: landfall-test
on: workflow_dispatch
jobs:
  fail:
    runs-on: ubuntu-latest
    steps:
      - run: exit 1

When the run fails, a new incident appears in Incidents, titled <owner>/<repo>: deploy-critical workflow "landfall-test" failed, at sev2. Each run opens one incident at most, so running the workflow again opens a second incident for the new run. Remove the test workflow from the list when you are done.

Repeats and recovery

Landfall identifies an alert by its event type, repository and alert number, and a workflow run by its run ID. Before opening anything, it looks for an incident it already opened for that identity. If there is one, the delivery is acknowledged and nothing new is added to the timeline. That covers GitHub's own redeliveries and an alert reopened later, even after the first incident was resolved.

A fixed, dismissed or resolved alert records nothing. Landfall never closes an incident because of a GitHub event; resolving it is your call.

Troubleshooting

What you see	What it means
An alert opens nothing	Its switch is off or was not saved, or the delivery was not a new or reopened alert. An alert that already opened an incident never opens a second one.
A failed workflow opens nothing	The owner, repository or path on the deploy-critical list does not match exactly, or the run did not end in failure (a cancelled run does not count).
The incident names the repository instead of a service	The repository has no service mapping. Add one; see Map repositories to services.
Nothing opens at all, and the GitHub connection shows as failing	The App was uninstalled or lost the repository. In the GitHub panel, click Disconnect, then Connect GitHub.

Reference

Endpoint	POST https://api.landfalls.ai/triggers/github
Auth	X-Hub-Signature-256, an HMAC-SHA256 of the body keyed with the App's one webhook secret. The organization comes from the body's installation ID.
Issue or rotate	Nothing to issue. Landfall holds the App's webhook secret.
Recognized by	The X-GitHub-Event header, then your switches and, for workflow runs, your deploy-critical list
Attach identity	Event type, repository and alert number for an alert; the run ID for a workflow run
Each delivery	Opens one incident, or is acknowledged as a repeat. An active maintenance window that covers it opens nothing. Never closes an incident.
Rejected payloads	A bad signature or an unknown installation is a uniform 401. Events you did not turn on get a 200 and are dropped.
Incident badge	github, the raw source name, until the Incidents list has a label for it
Access	Read-only. Landfall never dismisses an alert, comments on a run, or writes anything back to GitHub.

GitHub uses the same trigger pipeline as every other source; see Integrations architecture.