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

# GitHub Actions

GitHub Actions emits events for CI/CD activity in your repositories. Dstl8 receives `workflow_run` and `workflow_job` events as a single webhook source and infers a stream per repository, per event type.

#### Add a GitHub source

The webhook secret is generated by Dstl8 during source creation, so you'll create the source first and then paste the values into GitHub. Open GitHub and Dstl8 in separate tabs.

**1. Open the Add Source dialog**

In Dstl8, from **Sources**, click **Add Source** and select **GitHub**.

**2. Configure the source**

In the **Configure GitHub Source** dialog:

* **Name**: a unique name to identify this source (e.g. the repository or org name).

Click **Create**.

**3. Copy the webhook values**

Dstl8 displays the values you'll paste into GitHub:

| Field       | Notes                                                                           |
| ----------- | ------------------------------------------------------------------------------- |
| Payload URL | URL for the webhook, e.g. `https://<org_id>.app.dstl8.ai/src-<id>`.             |
| Secret      | Auto-generated. GitHub uses this to sign payloads, and Dstl8 uses it to verify. |

Keep this dialog open while you set up the webhook on the GitHub side.

**4. Add the webhook in GitHub**

In your GitHub repository:

1. Go to **Settings → Webhooks → Add webhook**.
2. Paste the **Payload URL** from Dstl8.
3. Set **Content type** to `application/json`.
4. Paste the **Secret** from Dstl8.
5. Under **Which events would you like to trigger this webhook?**, select **Let me select individual events** and check **Workflow runs** and **Workflow jobs**. Deselect any other events, including **Pushes** (which is selected by default).
6. Leave **Active** checked and click **Add webhook**.

GitHub sends a ping payload to test the endpoint. You should see a green check next to the new webhook with *Last delivery was successful*.

> Only `workflow_run` and `workflow_job` events are supported. Other event types (push, pull request, etc.) are rejected by the receiver. Make sure no other events are selected in the webhook settings.

**5. Trigger a workflow**

If your repository doesn't already have a workflow, add one to generate events. For example, `.github/workflows/ci.yml`:

```yaml
name: CI

on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Echo
        run: echo "Build triggered by ${{ github.event_name }} on ${{ github.ref }}"
```

Create a branch, edit a file, and push. The workflow runs and GitHub sends `workflow_run` and `workflow_job` events to Dstl8.

#### After creating

The source appears in the Sources list as Pending with 0 streams. Once GitHub starts forwarding events, Dstl8 detects two streams per repository:

* `workflow_run` keyed by repository name, e.g. `combat-tracker`
* `workflow_job` keyed by repository name, e.g. `combat-tracker`

The source transitions to Healthy once events are flowing. If you point the webhook at multiple repositories (via an org-level webhook), each repository contributes its own pair of streams.

#### Assign streams to workspaces

Streams need to be assigned to a workspace to be accessible. Open the source's actions menu (gear icon) and select **Assign Streams**, then check the streams you want the Default workspace (or any other workspace) to receive and Save.

See Assigning streams to workspaces for details.

#### Tips

* Use a separate GitHub source per repository (or per org) rather than pointing multiple repositories at the same endpoint with collisions in mind. Streams are keyed by repository name, so pointing two unrelated repos at the same source still works, but the streams sit side by side in the same source.
* For org-wide coverage, configure the webhook at the organization level (**Org Settings → Webhooks**) instead of per repository. The same Payload URL and Secret apply.
* If the ping delivery fails, check the secret in the Dstl8 source matches what you pasted into GitHub. Mismatches show up as 401 responses in GitHub's **Recent Deliveries** tab on the webhook.
* If events stop arriving, GitHub's **Recent Deliveries** tab shows the full request and response for each attempt and supports redelivery, which is the fastest way to debug.


---

# 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.controltheory.com/controltheory-documentation/dstl8-docs/sources/github-actions.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.