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.

By The SKaaS team. Last updated . Markdown version

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.

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*"]
  }'
How do I connect a repository?
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.

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.