> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub alert integration

> Send GitHub Dependabot, code scanning, and secret scanning alerts and failed Actions workflows to Flashduty On-call through a repository or organization webhook, and recover them once fixed.

Use a GitHub repository or organization webhook to send the GitHub events that need on-call attention to Flashduty On-call:

* **Security alerts**: Dependabot alerts, code scanning alerts, and secret scanning alerts. Each GitHub security alert maps to one Flashduty alert, which recovers when the alert is fixed, dismissed, or closed in GitHub.
* **Failed Actions workflows**: each workflow on each branch maps to one alert. It triggers when a run concludes with `failure`, `timed_out`, or `startup_failure`, and recovers when a later run of that workflow on the same branch succeeds.

Change events such as deployments and code pushes are not part of this integration.

<div className="hide">
  ## In Flashduty On-call

  ***

  You can obtain an integration push URL in either of the following ways.

  ### Use a dedicated integration

  1. In the Flashduty console, select **Channel** and open a channel
  2. Select **Configuration** → **Integrations** → **Private integration**, then click **Add an integration**
  3. Select **GitHub**, then click **Save**
  4. Open the generated integration card and copy the **Push URL**

  ### Use a shared integration

  1. In the Flashduty console, select **Integration Center → Alert Events**
  2. Select **GitHub** and enter an integration name
  3. Configure the default route and select a channel; after creation, add more rules under **Route** if needed
  4. Click **Save** and copy the generated **Push URL**
</div>

## Configure GitHub

***

A webhook can be created on a single repository or on an organization (covering every repository in it). A repository webhook requires admin access to the repository; an organization webhook requires the organization owner role.

<Steps>
  <Step title="Make sure the security features are on">
    Security alerts are only raised when the matching feature is enabled. Check under the repository's **Settings → Advanced Security**:

    | Feature | Cost |
    | :- | :- |
    | Dependabot alerts | Free for all repositories |
    | Code scanning (for example, the CodeQL default setup) | Free for public repositories; private repositories need GitHub Code Security |
    | Secret scanning | Free for public repositories; private repositories need GitHub Secret Protection |

    Skip this step if you only want Actions failures.
  </Step>

  <Step title="Add the webhook">
    1. Repository webhook: open the repository and click **Settings → Webhooks → Add webhook**. Organization webhook: open the organization and click **Settings → Webhooks → Add webhook**
    2. **Payload URL**: paste the full Flashduty push URL, including `integration_key`
    3. **Content type**: select `application/json` (`application/x-www-form-urlencoded` is also accepted)
    4. **Secret**: leave it empty. Flashduty identifies the integration by the `integration_key` in the push URL and does not verify signatures
    5. **SSL verification**: keep **Enable SSL verification**
    6. **Which events would you like to trigger this webhook?**: select **Let me select individual events**, clear the preselected **Pushes**, and select the events you need:
       * **Dependabot alerts**
       * **Code scanning alerts**
       * **Secret scanning alerts**
       * **Workflow runs**
    7. Keep **Active** selected and click **Add webhook**
  </Step>

  <Step title="Verify connectivity and the lifecycle">
    GitHub sends a `ping` event as soon as the webhook is added. Check under the webhook's **Recent Deliveries** that the response code is `200`. The `ping` only verifies that the URL is reachable and does not create an alert.

    * **Actions failure**: run a workflow that fails (for example, a `workflow_dispatch` workflow that runs `exit 1`) and confirm that Flashduty receives an alert. Then make the workflow pass on the same branch and confirm that the alert recovers.
    * **Security alert**: add a dependency version with a known vulnerability to a test repository. When Dependabot raises the alert, Flashduty triggers an alert; **Dismiss** the alert in GitHub and confirm that the Flashduty alert recovers.

    GitHub does not retry failed deliveries automatically. Use **Redeliver** in **Recent Deliveries** to resend any delivery from the past 3 days; a redelivered event merges into the original alert.
  </Step>
</Steps>

## Events and alert status

***

GitHub puts the event type in the `X-GitHub-Event` request header and the action in the `action` field of the body. Flashduty handles them as follows:

| Event | Triggers or updates the alert | Recovers the alert | Ignored (success response, no alert) |
| :- | :- | :- | :- |
| `dependabot_alert` | `created`, `reopened`, `reintroduced`, `auto_reopened` | `fixed`, `dismissed`, `auto_dismissed` | `assignees_changed` |
| `code_scanning_alert` | `created`, `reopened`, `reopened_by_user` | `fixed`, `closed_by_user` | `appeared_in_branch`, `updated_assignment` |
| `secret_scanning_alert` | `created`, `reopened`, `publicly_leaked` | `resolved` | `assigned`, `unassigned`, `validated`, `metadata_created`, `metadata_removed` |
| `workflow_run` | `completed` with conclusion `failure`, `timed_out`, or `startup_failure` | `completed` with conclusion `success` | `requested`, `in_progress`, and conclusions `cancelled`, `skipped`, `neutral`, `action_required`, `stale` |

`ping` and other event types (such as a `push` selected by mistake) also get a success response without creating an alert.

## Alert Key

***

* **Security alerts**: the Alert Key is built from the event type, the repository ID (`repository.id`), and the alert number (`alert.number`). The alert number is unique per repository and alert type, and GitHub uses it to address the alert in its API (for example, `/repos/{owner}/{repo}/dependabot/alerts/{alert_number}`). The Alert Key stays the same from creation through fix, dismissal, and reopening, and renaming the repository does not change it.
* **Actions failures**: the Alert Key is built from the repository ID, the workflow ID (`workflow_run.workflow_id`), the ID of the repository the run came from (`workflow_run.head_repository.id`), and the branch (`workflow_run.head_branch`). Later runs of the same workflow on the same branch, including **Re-run**, merge into this alert, and any successful run recovers it. Each branch and each workflow gets its own alert; a pull request from a fork never merges with a branch of the same name in your repository. A run without branch information gets its own alert keyed by the run ID (`workflow_run.id`), which recovers only when a **Re-run** of that run succeeds.

Events without `repository.id`, `alert.number`, `workflow_run.id`, or `workflow_run.workflow_id` are rejected.

## When alerts do not recover

***

In these cases no successful run follows, so the alert does not recover on its own:

* The branch was deleted or merged after the failure (for example, a pull request branch), or the workflow no longer runs on that branch
* The failed run has no branch information and was not re-run
* An older run on the same branch finished with a failure after a newer run succeeded

We recommend turning on the channel's [auto-resolve timeout](/en/on-call/channel/create-edit) with **Incident trigger** as the **Window timing start** and a **Timeout duration** of 24 hours. A failed workflow is normally fixed within a working day. Security alerts recover when they are fixed, dismissed, or closed in GitHub, so a channel that only receives security alerts can leave the timeout off.

## Severity

***

| Event | GitHub field | GitHub value | Flashduty severity |
| :- | :- | :- | :- |
| Dependabot | `alert.security_advisory.severity` | `critical`, `high` | Critical |
| | | `medium` | Warning |
| | | `low` | Info |
| | | Empty or other | Warning |
| Code scanning | `alert.rule.severity` | `error` | Critical |
| | | `warning` | Warning |
| | | `note`, `none` | Info |
| | | Empty or other | Warning |
| Secret scanning | No severity field | - | Critical |
| Actions failure | - | - | Warning (kept on recovery) |

A recovery event keeps the alert's existing severity.

## Labels

***

| Label | Source |
| :- | :- |
| `source` | Always `github` |
| `event` / `action` | Event type and action |
| `repository` / `repository_id` | Repository full name and ID |
| `alert_number` / `alert_url` | Security alert number and its link in GitHub |
| `check` | GHSA ID for Dependabot, rule ID for code scanning, secret type for secret scanning, workflow name for Actions |
| `severity` | Raw GitHub severity (Dependabot advisory severity or code scanning rule severity) |
| `package` / `ecosystem` / `manifest_path` / `ghsa_id` / `cve_id` | Dependency package, ecosystem, manifest file, and vulnerability IDs of a Dependabot alert |
| `tool` / `ref` | Code scanning tool and the branch of the most recent instance |
| `validity` | Whether the secret is still valid (`active`, `inactive`, `unknown`) |
| `workflow_path` / `branch` / `conclusion` / `trigger` | Workflow file, branch, run conclusion, and triggering event |
| `run_id` / `run_number` / `run_attempt` / `run_url` / `head_sha` | Workflow run ID, number, attempt, link, and commit |

## Troubleshooting

***

* **Recent Deliveries shows a failure**: open the delivery's **Response**. If it is not `200`, make sure the push URL is complete and includes `integration_key`. GitHub waits at most 10 seconds for a response
* **Ping succeeds but no alert arrives**: make sure the four events above are selected and the repository has the matching security features enabled. Cancelled or skipped workflow runs never create alerts, and a successful run only recovers an existing one
* **A security alert does not recover**: make sure the alert was fixed, dismissed, or closed in GitHub, and find the matching `fixed`, `dismissed`, `closed_by_user`, or `resolved` delivery in **Recent Deliveries**
* **An Actions failure alert never closes**: make sure a later run of that workflow succeeded on the same branch. For deleted branches and similar cases, see "When alerts do not recover" above

For field details, see GitHub's [Webhook events and payloads](https://docs.github.com/en/webhooks/webhook-events-and-payloads) and [Creating webhooks](https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks).