Skip to content

Commit 4e4607d

Browse files
authored
Publish the fizzy skill to basecamp/skills on release (#214)
* Publish the fizzy skill to basecamp/skills on release basecamp/skills is becoming the skills repo for every 37signals product, and Fizzy was the one CLI not publishing there. Stable releases now mirror skills/ into it with the same sync-skills.sh basecamp-cli and hey-cli run, which owns only this CLI's skills via a per-source manifest (.managed-skills.fizzy-cli) and never touches a sibling's (basecamp/skills#5). The job is continue-on-error and files a skills-sync issue on failure; sync-skills.yml is the manual recovery. The sibling repos' BATS test is ported to plain bash, since this repo's toolchain has no BATS, and runs as make test-scripts (part of make check) and in CI. * Name the pre-fix sibling test after what it tests * Converge on the seed's sync-skills.sh and its test The seed (basecamp/cli#78) went further than the hey-cli copy taken first: a rejected push re-applies the sync from the remote's new tip (matching git's "fetch first" as well as "non-fast-forward"), a name another source's manifest holds is refused before anything is copied, SYNC_SOURCE and DRY_RUN are validated, a dirty checkout is refused, and the token reaches git through a private config rather than the remote URL. basecamp-cli and hey-cli are converging on the same file, so every publisher runs one script; only the CLI_NAME default differs here. The seed's test-sync-skills.sh replaces the bash port of the BATS file: it covers the same ownership cases plus the racing publisher, the publish-side refusal, DRY_RUN=remote and the dirty-tree guard. * Always clone the skills target fresh; retire SKILLS_TARGET and its guards Mirrors basecamp/cli@966966e (the seed is the source of truth; only the CLI_NAME default differs here), and picks up the two seed commits this copy was behind: the remote-URL assert that read every configured URL, and two comment rewordings — both now moot, since the assert is gone. SKILLS_TARGET let the script adopt an existing checkout of basecamp/skills. Every release path clones its own target, and each review round found another corner of "any checkout" to guard. The script now always clones into a temp directory from SKILLS_REPO_URL (default https://github.com/basecamp/skills.git, the token carried through the same insteadOf rewrite as before), applies, pushes and cleans up, so the only commit it can push is the one it made. The remote-URL, branch and clean-tree asserts are gone with the knob; the retry from the fetched tip, the per-source manifests, the collision guard, the tombstone and DRY_RUN validation are unchanged. The test points SKILLS_REPO_URL at a local bare repository and reads every result back from a clone of its own; the race is staged with a post-commit hook that pushes the sibling's commit between the script's clone and push. * Say what the private gitconfig replaces, and what it does not Mirrors the seed (basecamp/cli#78 at 1df3bfe5). GIT_CONFIG_GLOBAL stands in for the user's global file only. The system config and any GIT_CONFIG_COUNT settings in the environment still reach every git call the script makes — the race test injects its hooks path through exactly that — so the comment no longer claims the ambient environment is kept out. * Skip the release-time skills sync for anything but the latest stable release The sync-skills job's concurrency group serialises the syncs but does not order them by version. An older stable release's job can reach the sync after a newer one has published — its run stalled, or its failed sync was rerun later, which is what the failure issue tells the operator to do — and the script mirrors the skills wholesale, so that run would roll basecamp/skills back to the older skill. The job now makes the check the manual Sync skills workflow already makes: the tag must be the repository's latest stable release, or the sync is skipped with a warning. A failed lookup fails the job, so the failure issue is filed rather than the sync skipped in silence. * Run the sync as the source its CLI_NAME default names Every case set SYNC_SOURCE to play hey-cli or basecamp-cli, so the one line this copy of the script changes — the CLI_NAME default — never ran. A last case runs the script with neither SYNC_SOURCE nor CLI_NAME set and checks the manifest it writes, the bot it commits as and the summary line against the source the Makefile expects, fizzy-cli. A copy left at the seed's placeholder, or naming another CLI, fails here instead of publishing under that source's manifest and identity. Mirrors seed/scripts/test-sync-skills.sh from basecamp/cli@19b52ed. * Send the token as a github.com-scoped Authorization header, not a URL rewrite Mirrors the seed (basecamp/cli#78 at 0649a4d); scripts/sync-skills.sh stays byte-identical apart from the CLI_NAME default, scripts/test-sync-skills.sh byte-identical. The insteadOf rewrite kept the token out of the outer git argv and the remote URL, but git expands the rewrite before invoking git-remote-https, so that helper still received https://x-access-token:<token>@github.com/... as an argument. The private gitconfig now carries http.https://github.com/.extraheader with the basic-auth form actions/checkout writes: the helper sees the plain URL, and the token lives only in the mode-600 file until the tmpdir goes. The test unsets SKILLS_TOKEN up front: its token-required case points the script at the real basecamp/skills, and a token inherited from the caller's environment would have let it clone and publish the fixtures there. The header now says exactly what the tombstone shields — the sources that have upgraded — rather than "anyone's skills": a pre-fix sibling still rewrites .managed-skills with its own names and a second pre-fix sibling still deletes those, the basecamp/skills#5 clobber confined to the CLIs yet to upgrade. * Say that make check runs the skills sync test too
1 parent 3e04236 commit 4e4607d

9 files changed

Lines changed: 1025 additions & 8 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,3 +150,120 @@ jobs:
150150
env:
151151
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
152152
AUR_KEY: ${{ secrets.AUR_KEY }}
153+
154+
# Mirrors skills/ into basecamp/skills, the distribution repo shared by every
155+
# CLI. The script owns only this CLI's skills there (.managed-skills.fizzy-cli)
156+
# and never touches a sibling's. continue-on-error: a stale skills repo must
157+
# not fail a release that has already shipped; the failure step files an
158+
# issue instead, and sync-skills.yml is the manual way back.
159+
sync-skills:
160+
name: Sync skills
161+
needs: [release]
162+
if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref_name, '-')
163+
continue-on-error: true
164+
concurrency:
165+
group: sync-skills
166+
cancel-in-progress: false
167+
runs-on: ubuntu-latest
168+
environment: release
169+
timeout-minutes: 10
170+
permissions:
171+
contents: read
172+
issues: write
173+
steps:
174+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
175+
with:
176+
persist-credentials: false
177+
178+
# An older stable release can reach this job after a newer one has
179+
# published — its run stalled, or its failed sync was rerun later — and
180+
# the script mirrors the skills wholesale, so it would roll basecamp/skills
181+
# back. The concurrency group serialises the jobs but does not order them,
182+
# so this is the check the manual Sync skills workflow makes: only the
183+
# latest stable release publishes. A failed lookup fails the job, which
184+
# files the issue below rather than skipping in silence.
185+
- name: Confirm this is the latest stable release
186+
id: latest
187+
env:
188+
GH_TOKEN: ${{ github.token }}
189+
TAG: ${{ github.ref_name }}
190+
run: |
191+
latest=$(gh release view --repo "${GITHUB_REPOSITORY}" --json tagName --jq .tagName)
192+
if [ "$TAG" = "$latest" ]; then
193+
echo "publish=true" >> "$GITHUB_OUTPUT"
194+
else
195+
echo "::warning::Skipping the skills sync for ${TAG}: the latest stable release is ${latest}, and syncing an older tag would roll basecamp/skills back."
196+
echo "publish=false" >> "$GITHUB_OUTPUT"
197+
fi
198+
199+
- name: Generate token for skills repo
200+
if: steps.latest.outputs.publish == 'true'
201+
id: skills-token
202+
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
203+
with:
204+
client-id: ${{ vars.RELEASE_CLIENT_ID }}
205+
private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
206+
owner: basecamp
207+
repositories: skills
208+
permission-contents: write
209+
210+
- name: Sync skills to distribution repo
211+
if: steps.latest.outputs.publish == 'true'
212+
id: sync
213+
env:
214+
SKILLS_TOKEN: ${{ steps.skills-token.outputs.token }}
215+
RELEASE_TAG: ${{ github.ref_name }}
216+
SOURCE_SHA: ${{ github.sha }}
217+
run: scripts/sync-skills.sh
218+
219+
- name: Notify on sync failure
220+
if: failure()
221+
env:
222+
GH_TOKEN: ${{ github.token }}
223+
REPO_SLUG: ${{ github.repository }}
224+
REF_NAME: ${{ github.ref_name }}
225+
RUN_ID: ${{ github.run_id }}
226+
run: |
227+
RUN_URL="https://github.com/${REPO_SLUG}/actions/runs/${RUN_ID}"
228+
LABEL="skills-sync"
229+
TITLE="Skills sync failure"
230+
BODY="The automatic skills sync to basecamp/skills for [${REF_NAME}](${RUN_URL}) failed. Check the workflow run for details; once fixed, rerun the failed jobs in that run or dispatch the Sync skills workflow for ${REF_NAME}."
231+
232+
# Filed on this repo (the only one github.token can write to), one
233+
# open issue per outage. Deduped by label, not title: a title lookup
234+
# misses the moment someone retitles the issue while triaging it.
235+
# The lookup fails closed — an API error must not read as "no open
236+
# issue" and file a duplicate; the annotation below still records
237+
# the failure.
238+
notify_status=0
239+
if ! matches=$(gh issue list --repo "$REPO_SLUG" --state open --label "$LABEL" \
240+
--json number --jq '[.[].number] | join(" ")'); then
241+
echo "::error::Could not list open '${LABEL}' issues in ${REPO_SLUG}. Filing nothing rather than risk a duplicate."
242+
notify_status=2
243+
else
244+
read -ra issues <<< "$matches"
245+
case "${#issues[@]}" in
246+
0)
247+
echo "No open '${LABEL}' issue; filing one."
248+
# --force makes this idempotent, so the label exists before the
249+
# first issue carries it (gh issue create refuses an unknown label).
250+
gh label create "$LABEL" --repo "$REPO_SLUG" --force \
251+
--color d93f0b --description "The release-time sync to basecamp/skills failed" \
252+
&& gh issue create --repo "$REPO_SLUG" --title "$TITLE" --body "$BODY" --label "$LABEL" \
253+
|| notify_status=$?
254+
;;
255+
1)
256+
echo "Commenting on existing '${LABEL}' issue #${issues[0]}."
257+
gh issue comment --repo "$REPO_SLUG" "${issues[0]}" --body "$BODY" || notify_status=$?
258+
;;
259+
*)
260+
# Picking one arbitrarily would scatter one outage's history
261+
# across issues a human already decided to keep separate.
262+
echo "::error::${#issues[@]} open issues carry the '${LABEL}' label (${issues[*]}). Refusing to guess which one to update — consolidate them, then re-run."
263+
notify_status=3
264+
;;
265+
esac
266+
fi
267+
268+
echo "::error::Skills sync to basecamp/skills failed for ${REF_NAME}. See ${RUN_URL}"
269+
exit "$notify_status"

‎.github/workflows/sensitive-change-gate.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ jobs:
1212
with:
1313
extra-patterns: |
1414
scripts/publish-aur.sh
15+
scripts/sync-skills.sh
1516
permissions:
1617
contents: read
1718
pull-requests: write

‎.github/workflows/sync-skills.yml‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Manual skills sync, for when the release-time sync could not run.
2+
#
3+
# The sync-skills job in release.yml is `needs: [release]`, so anything that
4+
# fails the release job after publication skips the sync entirely and leaves
5+
# basecamp/skills stale against a shipped release. A skipped or failed sync
6+
# needs a way back without cutting a new tag. This is it.
7+
#
8+
# scripts/sync-skills.sh mirrors the skills/ tree at the given ref into
9+
# basecamp/skills — only this CLI's skills, tracked in its own manifest there
10+
# (.managed-skills.fizzy-cli); other CLIs' skills are never touched — and no-ops
11+
# when the content already matches, so re-running it for an already-synced
12+
# release is safe.
13+
name: Sync skills
14+
15+
on:
16+
workflow_dispatch:
17+
inputs:
18+
tag:
19+
description: 'Release tag to sync from, with the v prefix (e.g. v4.1.0)'
20+
required: true
21+
type: string
22+
dry_run:
23+
description: 'Preview the sync without pushing'
24+
required: false
25+
default: false
26+
type: boolean
27+
28+
permissions: {}
29+
30+
# Shared with release.yml's sync-skills job so a manual run cannot interleave
31+
# with an automatic one.
32+
concurrency:
33+
group: sync-skills
34+
cancel-in-progress: false
35+
36+
jobs:
37+
sync:
38+
name: Sync skills
39+
runs-on: ubuntu-latest
40+
timeout-minutes: 10
41+
environment: release
42+
permissions:
43+
contents: read
44+
steps:
45+
- name: Validate tag input
46+
env:
47+
TAG: ${{ inputs.tag }}
48+
GH_TOKEN: ${{ github.token }}
49+
run: |
50+
# No prerelease suffix: the automatic sync in release.yml excludes
51+
# prereleases deliberately, and this path must not smuggle prerelease
52+
# content into the distribution repo's main branch.
53+
if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
54+
echo "::error::Invalid tag '${TAG}' — expected a stable v-prefixed semver tag (e.g. v4.1.0)"
55+
exit 1
56+
fi
57+
58+
# sync-skills.sh mirrors this CLI's skills wholesale, so syncing an
59+
# older tag would roll them back in basecamp/skills. The only reason to run this by
60+
# hand is that the newest release failed to sync — so require exactly
61+
# that release.
62+
latest=$(gh release view --repo "${GITHUB_REPOSITORY}" --json tagName --jq .tagName)
63+
if [ "$TAG" != "$latest" ]; then
64+
echo "::error::Refusing to sync ${TAG}: the latest stable release is ${latest}. Syncing an older tag would roll basecamp/skills back."
65+
exit 1
66+
fi
67+
68+
# Two checkouts: sync logic from the dispatching ref, skills content from
69+
# the release tag. A defect in scripts/sync-skills.sh is one of the ways
70+
# the automatic sync fails, and running the tagged copy here would just
71+
# re-run the defective script — recovery must be able to run a fix merged
72+
# to main without cutting a new tag.
73+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
74+
with:
75+
persist-credentials: false
76+
77+
# The content still mirrors the skills tree as it was released, even if
78+
# main has moved on since: SKILLS_SOURCE points the script at this
79+
# checkout. Fully qualified: actions/checkout resolves a bare name as a
80+
# branch before a tag, so a branch sharing the tag's name would win and
81+
# mirror unreleased content.
82+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
83+
with:
84+
ref: refs/tags/${{ inputs.tag }}
85+
path: release
86+
persist-credentials: false
87+
88+
# Needed for dry runs too: the honest preview clones the target, so it
89+
# cannot run tokenless. Dry runs get a read-only token, which is also what
90+
# stops DRY_RUN=remote from pushing even if the script were wrong.
91+
- name: Generate token for skills repo
92+
id: skills-token
93+
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
94+
with:
95+
client-id: ${{ vars.RELEASE_CLIENT_ID }}
96+
private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
97+
owner: basecamp
98+
repositories: skills
99+
permission-contents: ${{ inputs.dry_run && 'read' || 'write' }}
100+
101+
# github.sha is the dispatching ref's SHA (main), not the tag's, so
102+
# resolve the tagged commit from its own checkout — otherwise the sync
103+
# records the wrong provenance for the release it claims to mirror.
104+
- name: Resolve the tagged commit
105+
id: source
106+
env:
107+
TAG: ${{ inputs.tag }}
108+
run: echo "sha=$(git -C release rev-parse --verify "refs/tags/${TAG}^{commit}")" >> "$GITHUB_OUTPUT"
109+
110+
# DRY_RUN=remote clones the actual target and stops before the push, so
111+
# the preview shows the real diff including deletions.
112+
- name: Sync skills to distribution repo
113+
env:
114+
SKILLS_TOKEN: ${{ steps.skills-token.outputs.token }}
115+
RELEASE_TAG: ${{ inputs.tag }}
116+
SOURCE_SHA: ${{ steps.source.outputs.sha }}
117+
SKILLS_SOURCE: release/skills
118+
DRY_RUN: ${{ inputs.dry_run && 'remote' || '' }}
119+
run: scripts/sync-skills.sh

‎.github/workflows/test.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,9 @@ jobs:
3434
- name: Run tests
3535
run: go test -v ./...
3636

37+
- name: Test the skills sync
38+
run: make test-sync-skills
39+
3740
- name: Build
3841
run: go build -o bin/fizzy ./cmd/fizzy
3942

‎AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ fizzy-cli/
1313
│ ├── mcpserver/ # `fizzy mcp` MCP server (catalog/ synced from fizzy-mcp-server)
1414
│ └── render/ # Output rendering (styled, markdown, columns)
1515
├── e2e/ # Go integration tests
16-
├── skills/ # Agent skills
16+
├── skills/ # Agent skills (mirrored to basecamp/skills on release)
1717
└── .claude-plugin/ # Claude Code integration
1818
```
1919

@@ -113,7 +113,7 @@ Token-based via personal access tokens. Run `fizzy setup` for interactive config
113113

114114
## Checks
115115

116-
`make check` runs `fmt-check vet lint tidy-check race-test`. There is no `surface-check`
116+
`make check` runs `fmt-check vet lint tidy-check race-test test-sync-skills`. There is no `surface-check`
117117
in that list, but the surface gate still runs: `race-test` is
118118
`go test -race -count=1 ./internal/...`, which includes
119119
`internal/commands.TestSurfaceSnapshot`.

‎Makefile‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: test test-unit test-e2e e2e test-go test-file e2e-file test-run e2e-run build clean tidy help \
1+
.PHONY: test test-unit test-sync-skills test-e2e e2e test-go test-file e2e-file test-run e2e-run build clean tidy help \
22
check-toolchain fmt fmt-check vet lint tidy-check race-test vuln secrets \
33
replace-check security check release-check release tools \
44
surface-snapshot surface-check lint-actions
@@ -28,6 +28,7 @@ help:
2828
@echo "Usage:"
2929
@echo " make build Build the CLI"
3030
@echo " make test-unit Run unit tests (no API required)"
31+
@echo " make test-sync-skills Test the skills sync script (no API required)"
3132
@echo " make e2e Run owner-only CLI contract e2e tests"
3233
@echo " make test-e2e Alias for e2e"
3334
@echo " make test Alias for e2e"
@@ -50,7 +51,7 @@ help:
5051
@echo ""
5152
@echo " make lint-actions Lint GitHub Actions workflows"
5253
@echo " make security lint + vuln + secrets"
53-
@echo " make check fmt-check + vet + lint + test-unit + tidy-check"
54+
@echo " make check fmt-check + vet + lint + tidy-check + race-test + test-sync-skills"
5455
@echo " make release-check check + replace-check + vuln + race-test"
5556
@echo " make release Run release preflight and tag"
5657
@echo " make tools Install dev tools"
@@ -92,6 +93,10 @@ build: check-toolchain
9293
test-unit: check-toolchain
9394
go test -v ./internal/...
9495

96+
# Test the skills sync script against a throwaway basecamp/skills checkout (no network)
97+
test-sync-skills:
98+
EXPECTED_SOURCE=fizzy-cli scripts/test-sync-skills.sh
99+
95100
# Run e2e tests (requires API credentials)
96101
e2e: build
97102
@if [ -z "$$FIZZY_TEST_TOKEN" ]; then echo "Error: FIZZY_TEST_TOKEN not set"; exit 1; fi
@@ -175,8 +180,8 @@ replace-check:
175180
# Security suite
176181
security: lint vuln secrets
177182

178-
# Local CI gate (fmt, vet, lint, tidy, race-test)
179-
check: fmt-check vet lint tidy-check race-test
183+
# Local CI gate (fmt, vet, lint, tidy, race-test, skills sync test)
184+
check: fmt-check vet lint tidy-check race-test test-sync-skills
180185

181186
# Release preflight
182187
release-check: check replace-check vuln

0 commit comments

Comments
 (0)