# GitHub

EvoHub receives GitHub events through a repository or organization **webhook**. It pages on what breaks your default branch — failed workflow runs and deployments — and on security alerts, and resolves them when GitHub reports them fixed.

## Set it up

:::steps
### Create the integration
In EvoHub, go to **On-Call → Integrations → + Add Integration**, choose **GitHub**, pick an **Escalation Policy** and click **Create Integration**. Copy the **Webhook URL**.
### Generate a signing secret
Open the integration and, under **Signing secret**, click **Generate secret**. Copy it — it is shown once.
### Add the webhook
In GitHub, open the repository (or organization) **Settings → Webhooks → Add webhook**. Set **Payload URL** to your webhook URL, **Content type** to `application/json`, and **Secret** to the signing secret.
### Choose the events
Pick **Let me select individual events** and tick **Workflow runs**, **Deployment statuses**, and any of **Dependabot alerts**, **Code scanning alerts** and **Secret scanning alerts** that should page. Click **Add webhook**.
:::

GitHub sends a **ping** when the webhook is created. EvoHub answers it as a test: `200`, no alert.

## What pages

| GitHub event | Opens an alert when | Severity | Resolves when |
| --- | --- | --- | --- |
| Workflow runs | a run on the repository's default branch completes with `failure`, `timed_out` or `startup_failure` | high | the next run of the same workflow on that branch succeeds |
| Deployment statuses | a deployment ends in `failure` or `error` | critical for a production environment, high otherwise | the next deployment to the same environment succeeds |
| Dependabot alerts | an alert is created, reopened or reintroduced | the advisory's severity (critical, high, medium, low) | the alert is fixed or dismissed |
| Code scanning alerts | an alert is created or reopened on the default branch | the rule's security severity, or error → high, warning → medium, note → low | the alert is fixed on the default branch or closed |
| Secret scanning alerts | an alert is created, reopened or found publicly leaked | critical | the alert is resolved on GitHub |

A production environment is one GitHub marks as production, or one named `production`, `prod`, `prd` or `live`. Runs on other branches, cancelled or skipped runs, findings on pull request branches and every other event are answered `200` and open nothing.

EvoHub never reads or stores the secret a secret scanning alert is about — only its type, its validity and the link to the alert.

## What EvoHub reads

| EvoHub alert | Taken from |
| --- | --- |
| Title | The workflow and branch, the environment, or the alert's summary, with the repository — for example *CI failed on main (acme/shop)*. |
| Labels | `repository`, `event`, and per event `workflow`, `branch`, `conclusion`, `commit`, `environment`, `package`, `ghsa`, `cve`, `rule`, `tool`, `secret_type`, `validity`, and `url` — a link to the run, deployment log or alert. |

## Resolve and deduplication

An alert is identified by the repository and the workflow and branch, the environment, or the alert number. While it is open, the same failure again is recorded as **Retriggered** instead of paging again.

## Signature

With a signing secret set, every delivery must carry a valid `X-Hub-Signature-256` header (an HMAC-SHA256 of the body). A missing or wrong signature is refused with `403` and opens nothing. See [Signing secrets](https://docs-dev.evohub.io/integrations-overview.md#signing-secrets).

## Related

- [Integrations overview](https://docs-dev.evohub.io/integrations-overview.md)
- [GitLab](https://docs-dev.evohub.io/gitlab.md)
- [Jenkins](https://docs-dev.evohub.io/jenkins.md)
- [SonarQube](https://docs-dev.evohub.io/sonarqube.md)