Release recipe footguns: tap/bucket push auth fails with URL-embedded PAT (+ org-secret-on-move, Pages tag policy, version reuse)

Surfaced while shipping Basilisk v0.4.0 — the release pipeline failed repeatedly on issues that are systemic to the Shipwright release recipe, not the app. Documenting so Shipwright can codify the correct pattern and stop every consumer rediscovering them.

1. (Primary) Homebrew/Scoop publish uses URL-embedded PAT → auth rejected

The publish-homebrew / publish-scoop jobs push to the tap/bucket via:

git clone "https://x-access-token:${BREW_SCOOP_PAT}@github.com/Nimblesite/scoop-bucket.git" bucket

With a valid, present PAT this fails:

remote: Invalid username or token. Password authentication is not supported for Git operations.
fatal: Authentication failed for 'https://github.com/Nimblesite/scoop-bucket.git/'

GitHub rejects a PAT embedded in the clone URL this way.

Fix (proven working in Nimblesite/dart_mutant): check out the target repo with actions/checkout + token:, then git push:

- name: Checkout scoop-bucket
  uses: actions/checkout@v4
  with:
    repository: Nimblesite/scoop-bucket
    token: ${{ secrets.BREW_SCOOP_PAT }}
    path: bucket
# ...render manifest into bucket/, then:
- run: |
    cd bucket
    git config user.name  "github-actions[bot]"
    git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
    git add -A && git commit -m "..." && git push

Shipwright's release template should use checkout+token, never URL-embedded credentials.

2. Org secret must be re-granted to the repo on a repo move

BREW_SCOOP_PAT is a Nimblesite org secret with selected repository access. When a repo moves orgs (this one moved MelbourneDeveloper/Basilisk → Nimblesite/Basilisk), the secret resolves empty until the repo is added under Org Settings → Secrets and variables → Actions → BREW_SCOOP_PAT → Repository access. Recipe docs should call this out as a post-move checklist item; the guard message should point here (it does, which helped).

3. github-pages environment must allow v* tags, not just main

The Pages deploy job runs in environment: github-pages. If that environment's deployment-branch policy only allows main, a tag-triggered release deploy (v0.4.0) is rejected at the gate — the job fails with zero steps and no log, which is hard to diagnose. Fix: add a v* tag deployment-branch policy to the environment. Shipwright should document/provision this.

4. Never re-release an existing version

Re-pushing an already-published tag (v0.4.0) re-runs vsce publish, which the VS Code Marketplace rejects ("version already exists") under set -euo pipefail. There is no recovery except bumping the version. The recipe should make this explicit: to retry a release, bump to the next version (e.g. v0.4.1), don't re-tag.

Ask

Bake the canonical release contract into Shipwright (template + docs): checkout+token for tap/bucket pushes, the org-secret-access requirement (esp. on repo moves), the v* Pages env tag policy, and the no-version-reuse rule.

Filed from the Basilisk v0.4.0 release post-mortem (runs 26674551533 / 26675234469).

Locate Shipwright's release template and recipe documentation, then inspect the publish-homebrew, publish-scoop, and Pages deploy jobs. Confirm how authentication, org-secret access, tag-triggered environment policy, and version reuse are currently handled; done means the template and docs codify all four release requirements.