# Connect GitHub to a Shipfox workspace (https://www.shipfox.io/docs/integrations/github/setup)

Description: Install the GitHub App, limit repository scope, and prove that a push starts a run.

Connect GitHub so Shipfox can read a repository and receive events. The same
integration connection lets a workflow call selected GitHub tools. See the
[GitHub overview](https://www.shipfox.io/docs/integrations/github) for its capabilities.

## Before you begin [#before-you-begin]

You need access to workspace integration settings. You must also be able to
install a GitHub App on the target account or organization.

To verify a run, you also need an online runner with the `shipfox` label.

## Install the GitHub App [#install-the-github-app]

### Start the integration connection

Open **Settings → Integrations** in the workspace. Select **GitHub**, then
start the integration connection. Shipfox opens the GitHub App installation flow.

### Set the GitHub repository boundary

Select the GitHub account or organization. Choose only the repositories
Shipfox should reach. This selection is the hard repository boundary.
GitHub returns you to Shipfox.

### Record the integration connection slug

Open the new integration connection's menu. Select **Use this integration**. Copy the
slug from the trigger example. Workflows use that value as `source`.

New GitHub integration connections use **Only your projects' repositories** by
default.
This setting applies to explicit checkouts and repositories named by GitHub
tools.

Use [Manage GitHub repository
access](https://www.shipfox.io/docs/how-to/set-up-work/manage-github-repository-access) to change the
setting or the repositories selected in GitHub.

## Check event delivery [#check-event-delivery]

Make sure the integration connection is enabled in **Settings → Integrations**. Select
**View recent events**. Push to an allowed repository. The event journal should
show the GitHub event.

## Verify a triggered run [#verify-a-triggered-run]

[Create a project](https://www.shipfox.io/docs/how-to/set-up-work/create-project) from one repository
selected in GitHub. Add
`.shipfox/workflows/check-github-connection.yml` to that repository. Replace
`github_acme` with the integration connection slug. This is a complete
workflow:

```yaml
# yaml-language-server: $schema=https://www.shipfox.io/docs/workflow.schema.json
name: Check the GitHub integration connection
runner: shipfox

triggers:
  on_push:
    source: github_acme # Replace with the slug of your GitHub integration connection.
    event: push

jobs:
  check:
    steps:
      - env:
          GIT_REF: "${{ event.ref }}"
        run: printf 'Received push for %s\n' "$GIT_REF"
```

Commit and push the workflow to the project's default branch. Wait for **Check
the GitHub integration connection** to sync, then push one more safe commit. The workflow
file's first push may arrive before the new definition is ready.

Open the second push event and its linked run. Check the Git ref in the log.
Check that the job uses the same allowed repository.

The [GitHub events reference](https://www.shipfox.io/docs/integrations/github/events) lists the shipped
event names and payload behavior. The [reference for GitHub
tools](https://www.shipfox.io/docs/integrations/github/tools) lists the tools a workflow can call.