From b07b18ac914757d820cba5f29161064c792d471e Mon Sep 17 00:00:00 2001 From: Pedro Rodrigues Date: Sun, 19 Apr 2026 14:53:14 +0100 Subject: [PATCH 1/4] feat: add release-please tarball workflow --- .github/workflows/release-please.yml | 23 +++++++++++++++++++++++ AGENTS.md | 2 +- CONTRIBUTING.md | 2 +- 3 files changed, 25 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml index 6e573ef..3f6bbbc 100644 --- a/.github/workflows/release-please.yml +++ b/.github/workflows/release-please.yml @@ -50,3 +50,26 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: gh release upload ${{ steps.release.outputs.tag_name }} dist/*.tar.gz + + - name: Notify supabase-plugin + if: ${{ steps.release.outputs.release_created && secrets.SUPABASE_PLUGIN_DISPATCH_TOKEN != '' }} + env: + GH_TOKEN: ${{ secrets.SUPABASE_PLUGIN_DISPATCH_TOKEN }} + TAG_NAME: ${{ steps.release.outputs.tag_name }} + VERSION: ${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}.${{ steps.release.outputs.patch }} + run: | + SHA=$(git rev-parse HEAD) + + gh api repos/supabase-community/supabase-plugin/dispatches \ + --method POST \ + --input - < Date: Sun, 19 Apr 2026 15:16:27 +0100 Subject: [PATCH 2/4] chore: drop plugin dispatch from release flow --- .github/workflows/release-please.yml | 23 ----------------------- AGENTS.md | 2 +- CONTRIBUTING.md | 2 +- 3 files changed, 2 insertions(+), 25 deletions(-) diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml index 3f6bbbc..6e573ef 100644 --- a/.github/workflows/release-please.yml +++ b/.github/workflows/release-please.yml @@ -50,26 +50,3 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: gh release upload ${{ steps.release.outputs.tag_name }} dist/*.tar.gz - - - name: Notify supabase-plugin - if: ${{ steps.release.outputs.release_created && secrets.SUPABASE_PLUGIN_DISPATCH_TOKEN != '' }} - env: - GH_TOKEN: ${{ secrets.SUPABASE_PLUGIN_DISPATCH_TOKEN }} - TAG_NAME: ${{ steps.release.outputs.tag_name }} - VERSION: ${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}.${{ steps.release.outputs.patch }} - run: | - SHA=$(git rev-parse HEAD) - - gh api repos/supabase-community/supabase-plugin/dispatches \ - --method POST \ - --input - < Date: Wed, 6 May 2026 16:57:46 +0300 Subject: [PATCH 3/4] feat: automate release flow with GitHub App and per-skill version bumps - Switch release-please to use GitHub App token (GH_APP_ID / GH_APP_PRIVATE_KEY) so CI runs on release PRs, matching the pattern used in supabase-mcp - Add a second GitHub App token step scoped to supabase-community to dispatch the sync-agent-skills workflow in supabase-plugin immediately after each release - Add per-skill SKILL.md metadata.version bumps to release-please-config.json extra-files so skill versions are kept in sync automatically on every release Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .github/workflows/release-please.yml | 30 ++++++++++++++++++++++++++-- release-please-config.json | 10 ++++++++++ 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml index 6e573ef..d07a909 100644 --- a/.github/workflows/release-please.yml +++ b/.github/workflows/release-please.yml @@ -13,10 +13,17 @@ jobs: release-please: runs-on: ubuntu-latest steps: + - name: Generate GitHub App token (this repo) + id: generate-token + uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1 + with: + client-id: ${{ secrets.GH_APP_ID }} + private-key: ${{ secrets.GH_APP_PRIVATE_KEY }} + - uses: googleapis/release-please-action@v4 id: release with: - token: ${{ secrets.GITHUB_TOKEN }} + token: ${{ steps.generate-token.outputs.token }} - uses: actions/checkout@v4 if: ${{ steps.release.outputs.release_created }} @@ -48,5 +55,24 @@ jobs: - name: Upload release assets if: ${{ steps.release.outputs.release_created }} env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }} run: gh release upload ${{ steps.release.outputs.tag_name }} dist/*.tar.gz + + - name: Generate GitHub App token (supabase-community) + id: generate-token-plugin + if: ${{ steps.release.outputs.release_created }} + uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1 + with: + client-id: ${{ secrets.GH_APP_ID_SUPABASE_PLUGIN }} + private-key: ${{ secrets.GH_APP_PRIVATE_KEY_SUPABASE_PLUGIN }} + + - name: Trigger supabase-plugin skill sync + if: ${{ steps.release.outputs.release_created }} + env: + GH_TOKEN: ${{ steps.generate-token-plugin.outputs.token }} + run: | + gh workflow run sync-agent-skills.yml \ + --repo supabase-community/supabase-plugin \ + --field release_tag=${{ steps.release.outputs.tag_name }} \ + --field release_version=${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}.${{ steps.release.outputs.patch }} \ + --field commit_sha=${{ github.sha }} diff --git a/release-please-config.json b/release-please-config.json index 8a96d54..e4d4e5d 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -9,6 +9,16 @@ "type": "json", "path": "package.json", "jsonpath": "$.version" + }, + { + "type": "generic", + "path": "skills/supabase/SKILL.md", + "expressions": ["version: \"([0-9]+\\.[0-9]+\\.[0-9]+)\""] + }, + { + "type": "generic", + "path": "skills/supabase-postgres-best-practices/SKILL.md", + "expressions": ["version: \"([0-9]+\\.[0-9]+\\.[0-9]+)\""] } ] } From 47a367f51d42a7705dfaa449e59a054a8e15441d Mon Sep 17 00:00:00 2001 From: Pedro Rodrigues Date: Wed, 6 May 2026 16:57:54 +0300 Subject: [PATCH 4/4] docs: update CONTRIBUTING.md and AGENTS.md with accurate release flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove stale instruction to manually bump metadata.version (now automated) - Document end-to-end release flow: conventional commit → Release Please PR → GitHub release → tarballs → supabase-plugin dispatch - Add release-please-config.json registration step for new skills with the required extra-files JSON snippet - Add troubleshooting footnotes for bad-state Release Please PRs and missed supabase-plugin dispatches Co-Authored-By: Claude Sonnet 4.6 (1M context) --- AGENTS.md | 18 +++++++++++------- CONTRIBUTING.md | 33 +++++++++++++++++++++++++-------- 2 files changed, 36 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e65a814..4a77b9f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,9 +35,8 @@ pnpm test # Run tests This repository uses Release Please on `main`. - Merge conventional commits using `feat:` and `fix:` prefixes so Release Please can open or update the release PR. -- The release PR is the gate for semantic version bumps and changelog generation. -- When the release PR is merged, GitHub Actions creates a semver GitHub release and uploads one tarball per shipped skill from `dist/`. -- These GitHub releases are the source of truth for downstream consumers such as `supabase-community/supabase-plugin`, which poll upstream releases rather than receiving a cross-repo dispatch from this repository. +- The release PR bumps the repo version, updates the changelog, and bumps `metadata.version` in every skill's `SKILL.md` automatically via `extra-files` in `release-please-config.json`. Do not bump skill versions manually. +- When the release PR is merged, GitHub Actions creates a semver GitHub release, uploads one `.tar.gz` per skill as release assets, and dispatches the sync workflow in `supabase-community/supabase-plugin` to update downstream skills immediately. If you change shipped skill contents under `skills/`, make sure the change is represented with an appropriate conventional commit so it is included in the next release. @@ -49,7 +48,15 @@ Skills follow the [Agent Skills Open Standard](https://agentskills.io/). 2. Create `SKILL.md` following the format below 3. Add `references/_sections.md` defining sections 4. Add reference files: `{prefix}-{reference-name}.md` -5. Run `pnpm test` +5. Register the skill in `release-please-config.json` under `extra-files` so Release Please keeps its `metadata.version` in sync on every release: + ```json + { + "type": "generic", + "path": "skills/{skill-name}/SKILL.md", + "expressions": ["version: \"([0-9]+\\.[0-9]+\\.[0-9]+)\""] + } + ``` +6. Run `pnpm test` --- @@ -74,9 +81,6 @@ description: What this skill does and when to use it. | `license` | No | License name or reference to bundled license file. | | `metadata` | No | Arbitrary key-value pairs (e.g., `author`, `version`). | -**Version bumps:** Any change to `SKILL.md` or files in `references/` must bump -the `version` in the skill's frontmatter metadata before committing. - ### Name Field Rules - Lowercase letters, numbers, and hyphens only (`a-z`, `0-9`, `-`) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a49495..106ebe6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,14 +60,32 @@ All commands must complete successfully. ### Releases -This repository uses Release Please to manage semantic version releases. +Releases are automated via [Release Please](https://github.com/googleapis/release-please). It tracks commits on `main` and opens a release PR when there are releasable changes. -- Use conventional commit prefixes such as `feat:` and `fix:` in merge commits so Release Please can determine the next version. -- Release Please opens a release PR on `main` with the version bump and changelog updates. -- When that release PR is merged, GitHub Actions publishes a GitHub release and uploads one `.tar.gz` artifact per shipped skill. -- Those releases are consumed by downstream repositories, including the Supabase plugin repo, so they are part of the supported maintainer workflow. Downstream consumers are expected to poll these releases rather than rely on a cross-repo dispatch from this repository. +- Use conventional commit prefixes — `fix:` for a patch bump, `feat:` for a minor bump — so Release Please can determine the next version. +- Release Please opens a release PR on `main` that bumps the repo version, updates the changelog, and bumps `metadata.version` in every skill's `SKILL.md` automatically. You do not need to bump skill versions manually. +- Merging the release PR triggers GitHub Actions to: + 1. Create a GitHub release and git tag (e.g. `v0.2.0`) + 2. Package each directory under `skills/` into its own `.tar.gz` and upload them as release assets + 3. Dispatch the sync workflow in the Supabase plugin repo so downstream skills are updated immediately -If your PR changes shipped skill content, assume it is release-affecting and make sure the resulting merge commit uses the right conventional commit type. +#### Adding a new skill + +When you add a new skill, register its `SKILL.md` in `release-please-config.json` under `extra-files` so Release Please keeps its `metadata.version` in sync. Without this, the tarball will still be built and shipped but the skill's version will never be bumped. + +```json +{ + "type": "generic", + "path": "skills/my-skill/SKILL.md", + "expressions": ["version: \"([0-9]+\\.[0-9]+\\.[0-9]+)\""] +} +``` + +#### Troubleshooting + +> **Release PR in a bad state?** Close it and re-run the workflow from the [Actions tab](https://github.com/supabase/agent-skills/actions/workflows/release-please.yml) → **Run workflow**. Release Please will recreate the PR from scratch. + +> **Dispatch to supabase-plugin missed?** This can happen if the release workflow fails partway through. The sync workflow in supabase-plugin runs on a weekly schedule as a fallback, or you can trigger it manually from its [Actions tab](https://github.com/supabase-community/supabase-plugin/actions/workflows/sync-agent-skills.yml) → **Run workflow** and supply the release tag. ## Contributing New References @@ -77,8 +95,7 @@ To add a reference to an existing skill: 2. Copy `_template.md` to `{prefix}-{your-reference-name}.md` 3. Fill in the frontmatter (title, impact, tags) 4. Write explanation and examples (Incorrect/Correct) -5. Bump the `version` in the skill's `SKILL.md` frontmatter metadata -6. Run the tests: +5. Run the tests: ```bash pnpm test ```