Set up from a terminal

The tutorial sets up the hub and its projects in your browser. Every step works in a terminal as well, with the same checks and the same results on GitHub. You can mix both: the browser shows what the terminal did.

The hub: tapster init

Go to a clone of your tap and run init:

cd homebrew-tap
bunx @doguyilmaz/tapster init

init walks through five parts. Each part can run again and skips what is done. If anything stops it, run the same command again.

1. The hub is protected

Nothing to answer here. tapster:

• creates a tapster environment that only the main branch can open. Your keys go into it;
• adds a ruleset that keeps main from being deleted or force-pushed, by anyone including you;
• lets the hub’s workflows run only GitHub’s own actions and tapster’s, each pinned by commit;
• makes the workflows’ default token read-only.

Careful

Bringing an existing tap? Its other workflows stop running if they use actions from anyone else, such as the tests.yml and publish.yml that brew tap-new writes. The hub does not need them; delete them.

2. macOS or not

You should see

Will this hub sign software for macOS (Mac apps or CLI tools with macOS builds)? [Y/n]

Press Enter for yes. Answer n if you skipped the Apple step. tapster then leaves out the Apple parts below, and tapster add later leaves the macOS builds out of each project’s entry.

3. The App is created

The hub needs a GitHub App to write releases to your projects. tapster opens a page in your browser that shows the App and the permissions it asks for.

tapster waits here

tapster waits up to 30 minutes until GitHub sends you back. If no page opened, open the address above. Ctrl+C stops it.

1. Read the page and click Continue to GitHub.
2. GitHub shows the same App. Click Create GitHub App.
3. GitHub sends you back to a page that says Your tapster App is created. Close it.

Where your keys go

GitHub hands the App’s private key to tapster in your terminal. tapster stores it as a secret of the hub’s tapster environment. It goes nowhere else.

tapster then opens the App’s install page:

1. Choose Only select repositories.
2. Pick the project you will add in the next step. You can add more projects later.
3. Never pick the hub itself. The App can write to every repository it is installed on. The hub holds your keys.
4. Click Install.

tapster waits here

Waiting up to 10 minutes until the App is installed; tapster continues by itself once you choose Install.

tapster checks every few seconds. If you close the page without installing, it says so after 10 minutes and moves on. tapster add prints the install link for each project too.

4. Your Apple credentials

Drag each file from Finder into the terminal when tapster asks for it, then press Enter.

You should see

.p12 file (drag it here): then .p12 password:

Certificate stored for team ABCDE12345. It expires on 2031-02-01; the hub warns 30 days before.

tapster opens the .p12 with your password to check that it is a Developer ID Application certificate that has not expired. The password is not shown while you type.

You should see

.p8 file (drag it here):, Key ID: and Issuer ID:

Apple accepted the key. and Notarization key stored.

On a Mac, tapster asks Apple whether the key works before it stores it. Elsewhere Apple checks it at the first release.

Where your keys go

The certificate, its password and the notarization key become secrets of the hub’s tapster environment. Only workflows on main can read them. Keep your backups: GitHub never shows a secret again.

5. The files are written

You should see

wrote tapster.yml
wrote .tapster/state.json
wrote README.md
wrote .github/workflows/tapster.yml from the template, tapster v1.0.0 (61cd09d); hand edits in it are replaced
The hub looks for new drafts every 10 minutes; change it with tapster init --workflow --every <minutes>.

Done. Review and commit the new files, push, then run tapster add in each project.

tapster keeps files that already exist, such as your own README. The workflow pins the exact tapster you ran by its commit.

Commit and push them:

git add -A
git commit -m "Set up tapster"
git push

The hub is ready. It has no projects yet, so its runs find nothing to do.

A project: tapster add

Go to a clone of the project you want to publish and run add:

cd my-tool
bunx @doguyilmaz/tapster add

The first time, tapster asks which hub publishes the project and remembers the answer in the clone:

You should see

Which hub publishes this project (owner/repo)? Type you/homebrew-tap and press Enter.

tapster recognizes three kinds of projects. Each line it prints starts with - and says what it did.

1. The release workflow

• Go with GoReleaser (a .goreleaser.yaml next to go.mod): tapster turns on draft releases, names the checksum file checksums.txt and removes notarize, homebrew_casks, brews and scoops, because the hub does those now. In the workflow that runs GoReleaser (release.yml or the file you name with --workflow), it adds a step that attests the archives. See Move a GoReleaser project.
• Bun (a package.json with bin and a bun.lock): tapster writes .github/workflows/release.yml. It builds every platform in a job that can only read the repository. A second job attests the archives and opens the draft. See Bun projects.
• A Mac app with Sparkle: see Mac apps with Sparkle, which has its own order of steps.

Every release workflow also gets a step named Ring the tapster hub. It does nothing until you add the doorbell.

2. The project is protected

You should see

- protected you/my-tool: only you can create, move or delete branches and tags; workflows and Apps, the hub's included, cannot. Release tags come from you; GitHub then notes "Bypassed rule violations", which is your admin right at work.

This keeps a stolen App key from tagging code for your hub to sign. The rules cover every branch too: only you can push to the project now, so every push of yours shows the same note. Collaborators and bots such as Renovate or release-please can no longer push branches. Two cases have an option:

• A workflow that pushes its own release tags needs --auto-tag. See Releases tagged by a workflow.
• Dependabot opens its pull requests from branches, which the rules now close. See Dependabot.

3. The hub entry

tapster writes the project’s entry for the hub’s tapster.yml and opens a pull request on the hub with it:

You should see

- proposed the hub entry in https://github.com/you/homebrew-tap/pull/1; merge it to start publishing

If the repository’s GitHub description is one that Homebrew would reject, tapster says so and suggests a better one in the entry. Homebrew wants a short description that starts with a capital letter and has no full stop at the end.

Note

A project whose archives tapster cannot predict yet, for example GoReleaser with its own name template, gets no entry until its first draft exists. Run tapster add again after that.

4. The App’s install link

You should see

- open this page and choose Install, unless the hub's App already reaches you/my-tool; the project is preselected (keep "Only select repositories"): followed by a link.

If you picked this project when you created the hub, skip it. Otherwise open the link and click Install.

Your turn

tapster commits nothing. When it ends with Review the changes with git diff, then commit and push them., do this:

• Merge the pull request on your hub.

• Open the install link if tapster printed one for a project the App does not reach yet.

• Review the changes in the project, then commit and push them:

  git diff
  git add -A
  git commit -m "Release through tapster"
  git push

• Release. tapster’s last line is a gh command that tags the latest commit of the default branch on GitHub, with the next patch version after the highest tag there:

  gh api --method POST repos/you/my-tool/git/refs -f ref=refs/tags/v0.2.2 -f sha="$(gh api repos/you/my-tool/commits/main --jq 'if (.commit.message | test("(?i)\\[(skip ci|ci skip|no ci|skip actions|actions skip)\\]")) or ([.commit.message | splits("\\r?\\n[ \\t]*\\r?\\n") | select(test("\\S"))] | length > 1 and (last | test("(?im)^skip-checks:\\s*true\\s*$"))) then error("the latest commit of main carries a skip marker, so a tag on it may not start the release workflow") else .sha end')"

  It tags GitHub’s copy, not your clone, so a clone that is behind or on another branch cannot put the tag on the wrong commit. It stops when that commit’s message carries a skip marker such as [skip ci], because GitHub would start no release workflow for its tag. A project whose workflow tags by itself (--auto-tag) gets no command.

If you run tapster add again later, it changes no file that is already right. When the hub entry lacks what the project ships now, such as an app in its macOS archives, it prints the lines it would add and proposes them in a pull request on the hub that changes no other line. It never removes or rewrites what you wrote. What it cannot derive, such as entitlements, it lists for you to write by hand.

Where your keys go

The project holds no keys. If it still has old release secrets such as MACOS_* or HOMEBREW_TAP_*, tapster lists them. Delete them once the hub has published a release.

Check the hub

tapster doctor in a clone of the hub runs the same checks as Health in the browser and names the command that fixes each finding.