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

# GitHub Integration: Trigger Workflows on Repository Events

> Connect a GitHub repository to Shipfox with the GitHub App and trigger workflows on pushes and other repository events. Reference the connection by its slug.

The GitHub integration connects a repository or organization to Shipfox through a
**GitHub App**. Once connected, repository events — pushes and any other event the
App is subscribed to — can trigger workflow runs.

## Setup

<Steps>
  <Step title="Start the connection">
    In your workspace's integration settings, choose **GitHub** and start the
    connection. Shipfox sends you to GitHub to install its App.
  </Step>

  <Step title="Install the GitHub App">
    On GitHub, pick the account or organization and grant the App access to the
    repositories you want Shipfox to watch. GitHub redirects you back to Shipfox.
  </Step>

  <Step title="Copy the connection slug">
    Shipfox creates a **connection** for the installation. Its slug defaults to
    `github_<account>` — for example `github_acme`. This slug is the value you put
    in a trigger's `source` field.
  </Step>
</Steps>

## Triggering a workflow

Use the connection slug as `source` and a GitHub event name as `event`:

```yaml theme={null}
triggers:
  on_push:
    source: github_acme
    event: push
```

`source` is the connection **slug** (`github_acme`), not the word `github` — see
[Finding your connection slug](/integrations/overview#finding-your-connection-slug).

## Events

The most common event is `push`, which fires on every push to a connected
repository:

```yaml theme={null}
triggers:
  on_push:
    source: github_acme
    event: push
```

Shipfox forwards any GitHub webhook event the App is subscribed to, named
`<resource>` or `<resource>.<action>` (for example `pull_request.opened`,
`issues.opened`, `release.published`), passing the raw payload straight to your run.
Rather than duplicate GitHub's catalog here, use GitHub's own reference for the full
list of events and their payload shapes:

<Card title="GitHub webhook events and payloads" icon="github" href="https://docs.github.com/en/webhooks/webhook-events-and-payloads">
  The authoritative list of every GitHub webhook event and the payload it delivers.
</Card>

## Event payload

Shipfox passes the raw GitHub webhook payload to the run. For a `push`, that
includes the pushed ref, the head commit SHA, and the repository's default branch.

The branch ref is exposed to filters as `event.ref` — the **full Git ref** (for
example `refs/heads/main`), exactly as GitHub sends it.

## Filtering

You can add a `filter` CEL expression to target specific branches or actions — for
example `event.ref == "refs/heads/main"`:

```yaml theme={null}
triggers:
  on_main_push:
    source: github_acme
    event: push
    filter: event.ref == "refs/heads/main"
```

<Note>
  `filter` is parsed but **not yet evaluated** — the trigger fires on every `push`
  regardless of the expression. Authoring a filter now is safe and takes effect
  once evaluation ships. To gate behavior on the branch today, branch inside a
  `run` step.
</Note>

## Related pages

<CardGroup cols={2}>
  <Card title="Checks on push" icon="circle-check">
    A worked example that runs tests and an AI review on every push.
  </Card>

  <Card title="Triggers" icon="bolt">
    The trigger schema and how sources and events fit together.
  </Card>
</CardGroup>