> For the complete documentation index, see [llms.txt](https://docs.ilert.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ilert.com/integrations/deployment-integrations/github.md).

# GitHub deployment pipeline

Two ways to get GitHub events into ilert, and they answer different questions.

|                                                                                     | Use it when                                                             | Reports                                       |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------- |
| **Webhook**                                                                         | You want coverage now, across every repository, with nothing checked in | That a commit, merge, or release *happened*   |
| [**GitHub Action**](https://github.com/marketplace/actions/ilert-deployment-events) | You care whether the rollout actually succeeded                         | That a deployment *finished*, and how it went |

The webhook is the faster start and is enough for most accounts. Reach for the Action when "merged to main" and "live in production" are hours and a pipeline apart.

## Create the pipeline

Follow [Create a deployment pipeline](/integrations/deployment-integrations.md#create-a-deployment-pipeline) and choose type **GitHub**. Both setups below need the **URL** from the pipeline's detail view.

Two settings on that form matter here:

* **Branch filters** arrive prefilled with `main` and `master`. Pushes to any other branch are dropped. Clear the field to keep them all.
* **Event filters** — *Pull request (merged)*, *Commit (push)*, *Release (published)* — decide which of the webhook's events are recorded. Leave it empty and everything GitHub sends is kept.

{% hint style="info" %}
Prefer **Release (published)**. It is the easiest to set up and correlates best, because a release is a thing you actually shipped. Push events from an organization-wide webhook can run to hundreds a day, and a correlation that matches everything explains nothing.
{% endhint %}

## Set up an organization webhook

One webhook covers every repository in the organization, which is why this is the fastest way to get useful coverage. Filter in ilert rather than in GitHub.

{% stepper %}
{% step %}

### Open the webhook form

In GitHub, go to your organization's **Settings** → **Webhooks** → **Add webhook**.

<figure><img src="/files/2xF3HUkk88kFq0BdTRyR" alt="The GitHub organization settings page with Webhooks selected in the sidebar."><figcaption><p>Organization settings, not repository settings — this is the level that covers everything.</p></figcaption></figure>
{% endstep %}

{% step %}

### Point it at ilert

Paste the pipeline's **URL** into **Payload URL**, and change **Content type** to `application/json` — GitHub's default is `application/x-www-form-urlencoded`, which ilert does not accept.

Leave **Secret** empty and **SSL verification** enabled.
{% endstep %}

{% step %}

### Choose the events

Select **Let me select individual events**, then tick **Pull requests**, **Pushes**, and **Releases** — or tick all of them and narrow it later in the pipeline's event filters, which does not require touching GitHub again.

<figure><img src="/files/c2Psm4jcCNcCAibf4BSr" alt="The GitHub individual event selection list, showing Pull requests among the available event types."><figcaption><p>Ticking generously here and filtering in ilert keeps later changes on the ilert side.</p></figcaption></figure>
{% endstep %}

{% step %}

### Add it and confirm

Click **Add webhook**, then push a commit or publish a release and check that a row appears under **Alerting** → **Deployment events** in ilert. GitHub's own **Recent Deliveries** tab shows the response ilert returned.
{% endstep %}
{% endstepper %}

## Set up a repository webhook

For a single repository, the form is the same one level down: repository **Settings** → **Webhooks** → **Add webhook**, then follow the steps above from **Point it at ilert**.

<figure><img src="/files/liOfDwq9jjKzvcw4gd4G" alt="The GitHub repository settings page with Webhooks selected in the sidebar."><figcaption><p>Same form, scoped to one repository.</p></figcaption></figure>

## Report from a workflow instead

A webhook fires when the code moved in GitHub. If you want the event to mean *the rollout finished*, send it from the workflow that does the rolling out, using the [ilert deployment events action](https://github.com/iLert/ilert-deployment-events-action).

Store the pipeline's integration key as a repository secret — `ILERT_DEPLOYMENT_PIPELINE_INTEGRATION_KEY` below — rather than inlining it.

Mapped to repository events:

```yaml
on:
  push:
    branches:
      - master
      - main
  pull_request:
    branches:
      - master
      - main
    types:
      - closed

jobs:
  send-ilert-deployment-event:
    runs-on: ubuntu-latest
    name: Sending ilert deployment event
    steps:
      - name: Create a deployment event
        uses: iLert/ilert-deployment-events-action@master
        with:
          integration-key: ${{ secrets.ILERT_DEPLOYMENT_PIPELINE_INTEGRATION_KEY }}
```

Or reporting the outcome of your own deploy job, which is the version worth the extra work:

```yaml
on:
  push:
    branches:
      - master
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    name: Deploying the application (dummy)
    steps:
      - name: Dummy step
        run: echo "Dummy deployment"

  notification:
    runs-on: ubuntu-latest
    name: Notify ilert
    needs: [deploy]
    if: always()
    steps:
      # make deploy job status available
      # see https://github.com/marketplace/actions/workflow-status-action
      - uses: martialonline/workflow-status@v3
        id: check
      - name: Create a deployment event
        uses: iLert/ilert-deployment-events-action@master
        with:
          integration-key: ${{ secrets.ILERT_DEPLOYMENT_PIPELINE_INTEGRATION_KEY }}
          custom-event: Deployment ${{ steps.check.outputs.status }}
```

`if: always()` is what makes the second workflow useful: without it the notification job is skipped when `deploy` fails, and ilert only ever hears about the deployments that went well.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ilert.com/integrations/deployment-integrations/github.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.