set-up-github

Set up GitHub

Run this skill by hand from the repository you want to configure, once per repository. It changes settings on GitHub, not the local clone, so it does not need to run again in other clones. It needs gh logged in with admin rights on the repository, and jq installed.

The script is scripts/set-up-github.sh in this skill's folder, the folder that holds this SKILL.md. Run it with the repository as the working directory.

What it sets

• Merge settings: squash merges only. The squash commit title is the PR title and the body is blank. Head branches are deleted after merge. Other settings are left as they are.
• Ruleset trunk-based on the default branch: changes go through a pull request, and squash is the only allowed merge method. No approvals are required, which suits a single maintainer. The ruleset has no bypass actors, so direct pushes to the default branch are blocked for everyone.
• CI gate, only when CI exists: each named check must pass before merge, and the branch must be up to date with the default branch first. GitHub only enforces "up to date" when at least one required check exists.

Steps

1. Find the CI checks. Run scripts/set-up-github.sh --discover-checks. It lists the check names reported on the default branch.

   • If it lists names, show them to the user and ask which ones must pass before merge. Use only names the user picks, and pass each one with --check NAME. Do not guess names.
   • If it says no check runs exist, the repository has no CI reporting yet. Continue without --check. Tell the user the CI gate and the up-to-date rule are skipped, and that they apply once a CI job exists and this skill is run again.
   • Done when you have the check names, or the user has chosen none.

2. Dry run. Run scripts/set-up-github.sh --dry-run with the same --check flags. It prints the settings and ruleset it would apply and changes nothing. Show the output to the user and wait for them to confirm.

   • Done when the user has confirmed. If they decline, stop.

3. Apply. Run scripts/set-up-github.sh with the same --check flags. It updates the repository settings, then creates the ruleset, or updates it if one named trunk-based already exists. Running it again is safe.

   • If the script stops after the settings step, say which step failed. The repository settings may already have changed, and the ruleset may not exist. Report the error text and stop. Do not retry blindly.
   • A private repository on a plan without rulesets returns an error from the ruleset step. Report it. The settings step has already run.

4. Report. Print the script's verification lines. Say which parts were skipped and why. Remind the user that a required check name must match the check run name exactly. If the name never reports, pull requests wait forever, so it is worth checking the first PR after setup.

   • Done when the report is written.