# The GitHub App and the mirror

> Install the SKaaS GitHub App to publish skills from a repository on push, audit pull requests as a check, and keep a push-only mirror of your releases in a repository that you own.

Source: https://skaas.io/docs/github-app
Last updated: 2026-11-15

The GitHub App connects a GitHub repository to a SKaaS repository in two directions. A binding reads from GitHub: a push publishes, and a pull request is audited. A mirror writes to GitHub: a release that a push published is copied into a second repository that you own. A mirror follows the bindings of its SKaaS repository, so it needs one.

Edition and plan: the GitHub mirror needs the `github_mirror` feature, which is in Cloud Team and above and in the Community edition. Bindings and pull request checks have no plan limit.

## How do I connect a repository?

Install the app on the GitHub account that owns the repository, then create a **binding** on the SKaaS repository. The installation has to belong to your organization, and it has to reach the GitHub repository. You need the `repos:admin` scope.

```sh
curl -sS -X POST "https://api.skaas.io/v1/repos/$REPO_ID/github/bindings" \
  -H "authorization: Bearer $SKAAS_TOKEN" -H "content-type: application/json" \
  -d '{
    "installation_id": 4242,
    "github_repository": "acme/skills",
    "paths": ["skills/*"],
    "tag_patterns": ["v*"]
  }'
```

| Field          | Meaning                                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `paths`        | Which skill directories to read, as globs on the path from the repository root. `!pattern` leaves a match out. Empty reads the whole repository. |
| `branch`       | The branch whose pushes move `latest`. Absent means the default branch.                                                                          |
| `tag_patterns` | Tag globs. A tag that matches one moves `stable`. Empty ignores tags.                                                                            |
| `label`        | A short name that tells two bindings of one repository apart in a check title.                                                                   |

The app needs read access to contents and pull requests, write access to checks, and the `push`, `pull_request`, `installation` and `installation_repositories` events. Point its webhook at `/webhooks/github` on your API host. The webhook secret has at least 32 random characters, and SKaaS refuses a delivery whose signature does not match.

## What happens on a push?

SKaaS downloads the commit, finds the directories that hold a `SKILL.md` under your paths and publishes each one through the normal publish pipeline, with the same audit and policy as a publish from the CLI. A push to the tracked branch moves `latest`. A tag that matches a pattern moves `stable`. A directory whose release is already the head is skipped, so a push that changes nothing publishes nothing. A late delivery that no longer matches the tip of the branch changes nothing.

## What happens on a pull request?

The app audits the skills that the pull request changes and reports one check run, with the findings as annotations. It never publishes. A suspended installation, or one that belongs to another organization, feeds nothing.

## What is the mirror?

A push-only copy of your releases. When a push through a binding publishes a release and moves `latest`, SKaaS writes the release into a branch of the mirror repository, as a new commit on top of the branch. It never forces a push and it never reads from the mirror, so a change made there does not come back. A target that is the source branch itself is skipped. The mirror holds one folder per skill under a directory that defaults to `skills`. A release that you publish from the CLI is not copied.

```sh
curl -sS -X POST "https://api.skaas.io/v1/repos/$REPO_ID/github/mirrors" \
  -H "authorization: Bearer $SKAAS_TOKEN" -H "content-type: application/json" \
  -d '{ "installation_id": 4242, "github_repository": "acme/skills-mirror", "branch": "main" }'
```

Set `"enabled": false` to pause it. The app needs write access to contents on the target repository. Delete a binding or a mirror with the matching `DELETE` route, or remove the installation, which removes its bindings and mirrors.

## Where do I set it up?

In the dashboard, open the repository and choose **Integrations**. The section **The GitHub App** lists the bindings and the mirror targets, with a form to add each. The forms offer the installations that belong to your organization, each with the repositories that it reaches, and a suspended installation is listed with its state and cannot be picked. A repository that the chosen installation does not reach is refused before the call. The list comes from `GET /v1/orgs/{org}/github/installations`, which needs the `repos:admin` scope. Each part loads and fails alone, so a failing mirror list does not hide the bindings, and a list that did not load says so in the form.

A deployment that has no GitHub App shows the section with the words "The GitHub App is not set up on this deployment". Whoever runs it registers a GitHub App and sets `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY` and `GITHUB_WEBHOOK_SECRET` on the server. Set all three or none: the server refuses to start with only some of them, and with none it serves no webhook route. The mirror section shows "Mirror targets are not in your plan" when the plan lacks the `github_mirror` feature.

## What does it not do yet?

An administrator links a new installation on the **GitHub App** screen of the organization settings. Set the setup address of the GitHub App to `<web address>/github/setup`: GitHub sends the person back there, and the screen asks them to confirm the installation. The API exposes the same two setup steps. `POST /v1/orgs/{org}/github/setup` returns a `state` value and the App installation URL. The state belongs to that person and organization, works once and expires after 15 minutes. Enable “Request user authorization (OAuth) during installation” in the GitHub App settings and configure its callback. GitHub returns `installation_id`, `state` and `code`; send all three to `POST /v1/orgs/{org}/github/setup/complete`. Both routes require a signed-in session and `repos:admin`. The deployment needs `GITHUB_APP_CLIENT_ID` and `GITHUB_APP_CLIENT_SECRET` as well as the App identifier, private key and webhook secret. Without both OAuth settings, setup is unavailable. The server exchanges the code for a user token and confirms that the user can reach that installation. It uses that token for this check only, without storing or logging it. An installation linked to another organization cannot be moved by setup. GitHub webhook deliveries are deduplicated for 24 hours; failed work releases its claim for redelivery. Pull request checks apply repository policy without waivers.
