Onboarding

Onboarding

Take a fresh fork from "Use this template" to a green build on main.

Every step has two routes: a gh command and a by-hand walkthrough through the GitHub website (or git). They do the same thing, so use whichever suits you — the by-hand route is written for someone who has never opened these settings before. Substitute your own {owner}/{repo} throughout.

Before you start

• You need admin on the repository for every step below.
• For the gh route, run gh auth login and authenticate as that admin.
• Two different Settings pages are involved. Most steps are in the repository's settings — open your repository and click Settings in the top bar. The token in step 5 is in your account's settings — click your profile picture, top right. They look similar; check the sidebar heading.
• Only step 5 has no shortcut, because only you can mint a personal access token.

1. Rename the project

See the Quick start in README.md. Three identity sites, and just test-contract fails when they disagree.

2. Enable Actions

Without this no workflow runs at all, including the first build.

• gh — gh api -X PUT repos/{owner}/{repo}/actions/permissions -F enabled=true -f allowed_actions=all
• By hand:
  1. Open your repository and click the Actions tab.
  2. GitHub shows "Workflows aren't being run on this repository" with a green button. Click I understand my workflows, go ahead and enable them.
  3. To set the broader permission, go to Settings → Actions → General. Under Actions permissions, select Allow all actions and reusable workflows, then click Save.

3. Allow auto-merge

Renovate merges low-risk updates on its own, and it cannot without this.

• gh — gh api -X PATCH repos/{owner}/{repo} -F allow_auto_merge=true
• By hand:
  1. In your repository, click Settings.
  2. In the left sidebar, click General.
  3. Scroll down to Pull Requests.
  4. Tick Allow auto-merge. This section has no Save button; it applies immediately.
  5. Automatically delete head branches is optional. The template does not depend on it.

4. Workflow permissions

Two settings on one screen. The first lets workflows write — push images, open pull requests. The second is what lets the promotion workflow approve the check runs GitHub holds for its own pull request.

• gh — gh api -X PUT repos/{owner}/{repo}/actions/permissions/workflow -f default_workflow_permissions=write -f can_approve_pull_request_reviews=true
• By hand:
  1. Settings → Actions → General.
  2. Scroll down to Workflow permissions.
  3. Select Read and write permissions.
  4. Tick Allow GitHub Actions to create and approve pull requests.
  5. Click Save.

5. Create the Renovate token

The one step with no shortcut. Renovate uses this token to push branches and open pull requests, so it needs to act as you.

Skip this step if you do not want Renovate. Without the secret the workflow logs a skip and the run stays green; nothing else in the image depends on it.

Create the token

1. On any GitHub page, click your profile picture in the top right, then Settings.

2. In the left sidebar, click Developer settings.

3. Under Personal access tokens, click Tokens (classic).

4. Click Generate new token, then Generate new token (classic).

5. Give it a Note, for example renovate-your-repo.

6. Set an Expiration. The default is 30 days. When it lapses, Renovate stops opening pull requests until you replace the secret, so pick a date you will notice.

7. Under Select scopes, tick:

   • repo — read and write the repository
   • workflow — update the files under .github/workflows/

8. Click Generate token.

9. Copy the token now. GitHub shows it once. If you lose it, generate another and replace the secret.

A classic token carries every permission you have, on every repository you can reach. If you would rather not, create a fine-grained token instead, scoped to this repository, with Contents: Read and write and Workflows: Write.

Store it as a secret

• gh — gh secret set RENOVATE_TOKEN --repo {owner}/{repo}, then paste the token when prompted.
• By hand:
  1. Back in your repository, go to Settings → Secrets and variables → Actions.
  2. Click New repository secret.
  3. Name it exactly RENOVATE_TOKEN.
  4. Paste the token into Secret, then click Add secret.

6. Create stable

Promotion opens a pull request into stable, so the branch has to exist before the first promotion can run. Create it from main.

• git — from a clone: git push origin main:stable
• gh — gh api -X POST repos/{owner}/{repo}/git/refs -f ref=refs/heads/stable -f sha="$(gh api repos/{owner}/{repo}/git/ref/heads/main --jq .object.sha)"
• By hand:
  1. In your repository, click the branch dropdown in the file list — it reads main.
  2. Click View all branches, then New branch.
  3. Name it stable and set the source to main.
  4. Click Create new branch.

Never commit to stable directly. It only ever receives the promotion.

7. Protect main

Require the validate check, so nothing lands without passing shellcheck and hadolint.

• gh:

  gh api -X PUT repos/{owner}/{repo}/branches/main/protection --input - <<'JSON'
  {
    "required_status_checks": {"strict": false, "contexts": ["validate"]},
    "enforce_admins": false,
    "required_pull_request_reviews": null,
    "restrictions": null
  }
  JSON

• By hand:

  1. Settings → Branches (newer repositories keep this under Rules).
  2. Click Add branch protection rule, or Add classic branch protection rule.
  3. Branch name pattern: main.
  4. Tick Require status checks to pass before merging.
  5. In the search box, type validate and select the validate check. It must be exactly validate. A check that has never run does not appear in the list — push something first if it is missing.
  6. Require a pull request before merging is optional. The template's convention is that main takes no direct pushes, but the setting is what enforces it.
  7. Click Create, or Save changes.