Skip to main content
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

1

Start the connection

In your workspace’s integration settings, choose GitHub and start the connection. Shipfox sends you to GitHub to install its App.
2

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.
3

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.

​
Triggering a workflow

Use the connection slug as source and a GitHub event name as event: 
triggers:
  on_push:
    source: github_acme
    event: push
source is the connection slug (github_acme), not the word github — see Finding your connection slug.

​
Events

The most common event is push, which fires on every push to a connected repository: 
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:

GitHub webhook events and payloads

The authoritative list of every GitHub webhook event and the payload it delivers.

​
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": 
triggers:
  on_main_push:
    source: github_acme
    event: push
    filter: event.ref == "refs/heads/main"
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.

Checks on push

A worked example that runs tests and an AI review on every push.

Triggers

The trigger schema and how sources and events fit together.