github-repo-settings

Files (1)

• SKILL.md

SKILL.md (first lines)

# GitHub repository settings (`gh` CLI)

Administer GitHub repo settings from the CLI. All commands use `gh`, so the repo
is inferred from the current directory's `origin` remote unless `--repo` is given.

## Sync labels to `.github/release.yaml`

`.github/release.yaml` only governs **PR labels** — the changelog generator reads
the labels on merged PRs, nothing else. So it is **not** the full set of labels a
repo should have. Two distinct purposes coexist:

- **Issue-triage labels** (`bug`, `enhancement`, `question`, `help wanted`, …):
  classify *reported* problems/requests, whether or not the repo cuts releases.
  They legitimately exist even when absent from `release.yaml`. **Do not delete
  them just because the changelog config doesn't reference them.**
- **PR / changelog labels** (`feature`, `fix`, `chore`, `dependencies`, …):
  classify the *change shipped*. These category labels are what `release.yaml`
  maps to categories. Area and ecosystem labels (`rust`, …) stay out of it and
  never select a category (see `github-pr-conventions`).
  **Without `release.yaml`, none are created**: nothing reads them (see
  `github-pr-conventions`), so the sync below does not apply. The labels
  Dependabot creates for its own PRs are its config's business (see the notes).

The same concept often has both: `bug` (issue) ↔ `fix` (PR), `enhancement` (issue)
↔ `feature` (PR). Inside one changelog category, listing both members of such a
pair is a duplicate — pick one (the PR-side label) and drop the other from
`release.yaml`; but keep the issue-side label alive on the repo. That is also
what `github-pr-conventions` assumes when it labels a PR: `fix`/`feature` by
default, `bug`/`enhancement` only where a repo still maps them.

The `"*"` catch-all in `release.yaml` is a wildcard, **not** a real label — never
create it.

Procedure:

1. Read `.github/release.yaml`, collect every concrete label it maps (drop `"*"`).
   These must all exist on the repo.
2. List current labels: `gh label list --limit 100`.
3. Create any release.yaml label that's missing. Add any repo label missing from
   release.yaml into the right category (or `exclude`) **if it's a category
   label**; leave issue-triage and area/ecosystem labels out of `release.yaml`
   but keep them on the repo.
4. Only delete a label when the user actually wants it gone — never purely because
   it's absent from `release.yaml`.

The block below is a superset: keep `breaking`, the issue-triage labels, and
only the category and exclude labels the repo's `release.yaml` maps (see the
notes after it).

```bash
gh label create feature       --description "New feature"                   --color 0e8a16 --force
gh label create fix           --description "Bug fix"                       --color d73a4a --force
gh label create chore         --description "Maintenance / housekeeping"    --color fef2c0 --force
gh label create dependencies  --description "Dependency updates"            --color 0366d6 --force
gh label create documentation --description "Documentation only"            --color 0075ca --force
gh label create breaking      --description "Backwards-incompatible change" --color b60205 --force
gh label create security      --description "Security fix"                  --color b60205 --force
gh label create deprecation   --description "Deprecates a feature, removed in a later release" --color fbca04 --force
gh label create performance   --description "Performance improvement"       --color 5319e7 --force
# the exclude label, only when release.yaml has an `exclude.labels` entry
gh label create ignore-for-release --description "Exclude from release changelog" --color ededed --force
# issue-triage labels stay even though release.yaml never maps them
gh label create bug         --description "Something isn't working" --color d73a4a --force
gh label create enhancement --description "New feature or request"  --color a2eeef --force
gh label list --limit 100   # verify
```

Notes:

- **`breaking` is always created alongside `release.yaml`.** If the file has
  no *Breaking changes* category, add one — as the **first** category, since
  GitHub files a PR under the first match and a breaking PR also carries its
  `feature`/`fix` label (see `github-actions-conventions` for the baseline file).
- Otherwise, only create the category labels the repo's `release.yaml` actually
  maps; the exclude label only makes sense alongside an `exclude.labels` entry.
- **Leave the ecosystem labels to Dependabot**, and create the ones a
  `labels` setting names (`dependency-update-conventions`); creating your own
  variant gives the repo two labels for one concept.
- `gh label create --force` upserts, so it is safe to re-run.
- Deleting a label removes it from every issue/PR it is on and **cannot be
  undone** — it is destructive. Absence from `release.yaml` is **not** a reason to
  delete; only do it when the user explicitly wants the label gone, and confirm
  the delete list first.
- Leave GitHub's default `bug` / `enhancement` colours and descriptions as-is
  unless asked to unify them with the new labels.

## Restrict merge methods to squash-only

```bash
gh repo edit --enable-squash-merge --enable-merge-commit=false --enable-rebase-merge=false
gh repo view --json mergeCommitAllowed,squashMergeAllowed,rebaseMergeAllowed   # verify
```

Expected verification output:

```json
{"mergeCommitAllowed":false,"rebaseMergeAllowed":false,"squashMergeAllowed":true}
```

This greys out the "Create a merge commit" and "Rebase and merge" buttons on
PRs, leaving squash as the only option. Adjust the flags to allow other methods
(e.g. `--enable-rebase-merge` to add rebase back).

## Auto-delete head branches on merge

```bash
gh repo edit --delete-branch-on-merge
gh repo view --json deleteBranchOnMerge   # verify -> {"deleteBranchOnMerge":true}
```

Once on, merging a PR deletes its head branch automatically (the branch is still
recoverable from the PR's "Restore branch" button for a while). Pass
`--delete-branch-on-merge=false` to turn it back off.

## Enable GitHub Pages in GitHub Actions mode

Any repo with a workflow that runs `actions/deploy-pages` (the `docs` pipeline
of `github-actions-conventions`) needs Pages switched on with **source "GitHub
Actions"** (`build_type: workflow`), never "Deploy from a branch" (`legacy`).

From leroyguillaume/claude, MIT.

More from leroyguillaume/claude