From 9710cc7912aa9695f0095797faadcadaddd97a52 Mon Sep 17 00:00:00 2001 From: Will Gordon Date: Wed, 4 Nov 2026 16:38:00 -0500 Subject: [PATCH 1/2] ci(release): automate releases with release-please and tag deploys Configure manifest-mode release-please for root github-tracker (bootstrapped at 1.0.0 from c63711d42eb125da7be9016a0d853a1cf8c6534d) and mcp (github-tracker-mcp@0.1.1 with x-release-please-version annotation and parity unit tests), replace publish-mcp.yml with release.yml using a scoped GitHub App installation token and OIDC npm trusted publishing, tag Cloudflare Worker deploys with the commit SHA and sanitized subject in deploy.yml, and document release setup in DEPLOY.md, CONTRIBUTING.md, and README.md. --- .github/workflows/deploy.yml | 19 ++++++--- .github/workflows/publish-mcp.yml | 35 --------------- .github/workflows/release.yml | 55 ++++++++++++++++++++++++ .release-please-manifest.json | 4 ++ CONTRIBUTING.md | 49 +++++++++------------ DEPLOY.md | 40 +++++++++++++++++ README.md | 2 +- mcp/README.md | 2 +- mcp/src/index.ts | 2 +- mcp/tests/version.test.ts | 71 +++++++++++++++++++++++++++++++ release-please-config.json | 34 +++++++++++++++ 11 files changed, 240 insertions(+), 73 deletions(-) delete mode 100644 .github/workflows/publish-mcp.yml create mode 100644 .github/workflows/release.yml create mode 100644 .release-please-manifest.json create mode 100644 mcp/tests/version.test.ts create mode 100644 release-please-config.json diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index e763fc3e..a7016ff6 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -29,8 +29,17 @@ jobs: VITE_JIRA_CLIENT_ID: ${{ vars.VITE_JIRA_CLIENT_ID }} VITE_SENTRY_DSN: ${{ vars.VITE_SENTRY_DSN }} VITE_TURNSTILE_SITE_KEY: ${{ vars.VITE_TURNSTILE_SITE_KEY }} - - uses: cloudflare/wrangler-action@953926a2e2182532811c01a25e53647d93bf07c0 # v4.1.3 - with: - apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} - accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} - command: deploy + - name: Deploy to Cloudflare Workers + env: + CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} + CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} + LC_ALL: C.UTF-8 + DEPLOY_TAG: ${{ github.sha }} + RAW_MSG: ${{ github.event.head_commit.message }} + run: | + DEPLOY_TAG="${DEPLOY_TAG:0:25}" + FIRST_LINE="${RAW_MSG%%$'\n'*}" + DEPLOY_MSG="$(tr -d '\000-\037\177' <<< "$FIRST_LINE")" + DEPLOY_MSG="${DEPLOY_MSG:0:100}" + DEPLOY_MSG="${DEPLOY_MSG:-manual deploy ${DEPLOY_TAG}}" + pnpm exec wrangler deploy --tag "$DEPLOY_TAG" --message "$DEPLOY_MSG" diff --git a/.github/workflows/publish-mcp.yml b/.github/workflows/publish-mcp.yml deleted file mode 100644 index dc167935..00000000 --- a/.github/workflows/publish-mcp.yml +++ /dev/null @@ -1,35 +0,0 @@ -name: Publish MCP Server -on: - push: - tags: ["github-tracker-mcp@*"] -jobs: - build-and-publish: - runs-on: ubuntu-latest - permissions: - contents: read - id-token: write - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - uses: ./.github/actions/setup - with: - registry-url: "https://registry.npmjs.org" - - run: pnpm --filter github-tracker-mcp run typecheck - - run: pnpm --filter github-tracker-mcp run build - - run: pnpm --filter github-tracker-mcp test - - run: cd mcp && pnpm publish --access public --no-git-checks - - create-release: - runs-on: ubuntu-latest - needs: build-and-publish - permissions: - contents: write - steps: - - name: Create GitHub Release - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - gh release create "${{ github.ref_name }}" \ - --repo "${{ github.repository }}" \ - --title "MCP Server ${{ github.ref_name }}" \ - --generate-notes \ - --notes $'## Install\n```bash\nnpx github-tracker-mcp@latest\n```\nSee [npm package](https://www.npmjs.com/package/github-tracker-mcp) for full documentation.' diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 00000000..258ff062 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,55 @@ +name: Release +on: + push: + branches: [main] +permissions: {} +concurrency: + group: release-please + cancel-in-progress: false +jobs: + release-please: + if: github.repository == 'gordon-code/github-tracker' + runs-on: ubuntu-latest + permissions: + contents: read + environment: release + outputs: + mcp_release_created: ${{ steps.rp.outputs['mcp--release_created'] }} + mcp_tag: ${{ steps.rp.outputs['mcp--tag_name'] }} + steps: + - name: Generate GitHub App token + id: app-token + uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0 + with: + client-id: ${{ vars.RELEASE_APP_CLIENT_ID }} + private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }} + permission-contents: write + permission-pull-requests: write + - name: Run release-please + id: rp + uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0 + with: + token: ${{ steps.app-token.outputs.token }} + config-file: release-please-config.json + manifest-file: .release-please-manifest.json + + publish-mcp: + needs: release-please + if: github.repository == 'gordon-code/github-tracker' && needs.release-please.outputs.mcp_release_created == 'true' + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write + environment: npm-publish + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.release-please.outputs.mcp_tag }} + persist-credentials: false + - uses: ./.github/actions/setup + with: + registry-url: "https://registry.npmjs.org" + - run: pnpm --filter github-tracker-mcp run typecheck + - run: pnpm --filter github-tracker-mcp run build + - run: pnpm --filter github-tracker-mcp test + - run: cd mcp && pnpm publish --access public --no-git-checks --provenance diff --git a/.release-please-manifest.json b/.release-please-manifest.json new file mode 100644 index 00000000..0649e553 --- /dev/null +++ b/.release-please-manifest.json @@ -0,0 +1,4 @@ +{ + ".": "0.1.0", + "mcp": "0.1.1" +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f48f976b..19c1cc94 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -108,45 +108,34 @@ type(scope): description Scope is optional. Use imperative mood: "add feature", not "adds feature" or "added feature". -## Releasing the MCP server +## Releases -The MCP server (`mcp/` package) is published to npm and GitHub Releases via CI. +Both the root application (`github-tracker`) and the MCP server (`github-tracker-mcp` in `mcp/`) are released automatically with [release-please](https://github.com/googleapis/release-please) via `.github/workflows/release.yml` (`release-please-config.json` and `.release-please-manifest.json`). -### First publish (manual) +- **Never hand-edit versions or changelogs:** Do not manually edit `version` in `package.json`, `mcp/package.json`, `mcp/src/index.ts` (`// x-release-please-version`), or `.release-please-manifest.json`, and do not hand-edit `CHANGELOG.md` or `mcp/CHANGELOG.md`. Never manually create or push `github-tracker@*` or `github-tracker-mcp@*` tags. +- **Conventional Commits drive release notes and version bumps:** + - `feat:` bumps the minor version and appears under **Features** + - `fix:` bumps the patch version and appears under **Bug Fixes** + - `perf:` bumps the patch version and appears under **Performance** + - `feat!:` / `fix!:` / `BREAKING CHANGE:` footer bumps the major version + - `docs:`, `chore:`, `ci:`, `refactor:`, `test:`, `build:`, `style:`, and `revert:` are hidden from changelog sections + - Changes under `mcp/` scope to `github-tracker-mcp`; all other paths scope to `github-tracker` +- **Release PR flow:** When releasable commits land on `main`, `release.yml` opens or updates a release PR that bumps versions and updates `CHANGELOG.md` / `mcp/CHANGELOG.md`. Merging that release PR creates the git tag (`github-tracker@x.y.z` or `github-tracker-mcp@x.y.z`), publishes the GitHub Release, and—when `github-tracker-mcp` is released—publishes the package to npm via OIDC trusted publishing (`release.yml`, environment `npm-publish`). -The very first publish must be done locally — OIDC trusted publishing can only be configured for packages that already exist on npm. +See [DEPLOY.md](DEPLOY.md#releases) for the maintainer setup (GitHub App permissions, `release` and `npm-publish` environments, npm trusted publisher binding, and tag ruleset). -1. Create an npm account at [npmjs.com](https://www.npmjs.com/signup) if you don't have one -2. Log in locally: `npm login` -3. Build and publish: +### First publish for forks (manual, one-time) + +If you are publishing your own renamed MCP package from a fork, the very first publish to npm must be done locally because npm OIDC trusted publishing can only be configured for packages that already exist on npm: + +1. Create an npm account at [npmjs.com](https://www.npmjs.com/signup) and log in locally (`npm login`) +2. Build and publish once: ```bash cd mcp pnpm run build pnpm publish --access public ``` - -### Trusted publishing setup (one-time, after first publish) - -CI publishes via npm OIDC trusted publishing — no tokens or secrets needed. - -1. Go to **npmjs.com > github-tracker-mcp > Settings > Trusted Publishers** -2. Add a trusted publisher: - - **Owner:** `gordon-code` - - **Repository:** `github-tracker` - - **Workflow filename:** `publish-mcp.yml` - -### Cutting a release - -```bash -cd mcp -pnpm version patch # or minor|major, or manually bump version in package.json -git add package.json -git commit -m "chore(mcp): bump version to X.Y.Z" -git tag github-tracker-mcp@X.Y.Z # The tag _must_ match the github-tracker-mcp@X.Y.Z pattern. -git push upstream main --follow-tags -``` - -`pnpm version` bumps `mcp/package.json`, commits, and creates a `github-tracker-mcp@X.Y.Z` tag. Pushing that tag to upstream triggers CI, which typechecks, builds, tests, publishes to npm, and creates a GitHub release. +3. On **npmjs.com > your package > Settings > Trusted Publishers**, bind your repository's `release.yml` workflow and `npm-publish` environment. ## Pull requests diff --git a/DEPLOY.md b/DEPLOY.md index d164a1fc..049200ac 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -257,6 +257,46 @@ pnpm run build wrangler deploy ``` +In CI (`.github/workflows/deploy.yml`), production deployments run `pnpm exec wrangler deploy --tag "$DEPLOY_TAG" --message "$DEPLOY_MSG"` with values passed via `env:` (`DEPLOY_TAG` truncated to 25 characters of `GITHUB_SHA`; `DEPLOY_MSG` taken from the first line of the commit message with ASCII control characters stripped and truncated to 100 UTF-8 characters under `LC_ALL=C.UTF-8`, or `manual deploy ` on `workflow_dispatch`). + +## Releases + +App (`github-tracker`) and MCP server (`github-tracker-mcp`) releases are automated with [release-please](https://github.com/googleapis/release-please) in manifest mode (`release-please-config.json` and `.release-please-manifest.json`) via `.github/workflows/release.yml`. + +### One-time maintainer setup + +1. **Create a dedicated GitHub App on `gordon-code`:** + - Go to **Organization settings → Developer settings → GitHub Apps → New GitHub App** (with webhook disabled). + - Set **Repository permissions**: + - **Contents:** Read & write (creates release branches, tags, and GitHub Releases) + - **Pull requests:** Read & write (opens/updates release PRs and applies `autorelease: pending` / `autorelease: tagged` labels; if label creation fails, also grant **Issues: Read & write**) + - **Metadata:** Read-only (mandatory) + - Install the App on `gordon-code/github-tracker` **only**. + - Record the **Client ID** and generate a **Private key** (`.pem`). + +2. **Create protected GitHub Actions environments:** + - Go to **Settings → Environments** on `gordon-code/github-tracker`: + - **`release` environment:** restrict **Deployment branches and tags** to branch `main` only. Add environment variable `RELEASE_APP_CLIENT_ID` (the App's Client ID) and environment secret `RELEASE_APP_PRIVATE_KEY` (the full `.pem` private key). + - **`npm-publish` environment:** restrict **Deployment branches and tags** to branch `main` only, with an optional required reviewer gate. + +3. **Rebind the npm OIDC trusted publisher (before merging the first MCP release PR):** + - npm allows only one trusted publisher per package. On [npmjs.com](https://www.npmjs.com/) under **`github-tracker-mcp` → Settings → Trusted Publishers**, update the binding from `publish-mcp.yml` to: + - **Owner:** `gordon-code` + - **Repository:** `github-tracker` + - **Workflow filename:** `release.yml` + - **Environment name:** `npm-publish` + +4. **Configure a repository tag protection ruleset:** + - Go to **Settings → Rules → Rulesets → New ruleset → New tag ruleset**. + - Target tag patterns `github-tracker@*` and `github-tracker-mcp@*`. + - Enable **Restrict creations**, **Restrict updates**, and **Restrict deletions**, and add only the release GitHub App and repository admins to the **Bypass list** so manual tag pushes cannot impersonate a release. + +### How releases work + +1. **Conventional commits on `main` → Release PR:** Every push to `main` triggers `.github/workflows/release.yml`, which mints a short-lived installation token via `actions/create-github-app-token` and runs `googleapis/release-please-action`. Using a GitHub App token (rather than `GITHUB_TOKEN`) ensures `pull_request` CI workflows run automatically on the proposed release PR. +2. **Bootstrap (`1.0.0`) and post-release cleanup:** `release-please-config.json` sets `"bootstrap-sha"` to `c63711d42eb125da7be9016a0d853a1cf8c6534d` and `"release-as": "1.0.0"` on the root `.` package. If only hidden commit types (`ci:`, `chore:`, `docs:`, `test:`, `refactor:`) exist after `bootstrap-sha`, release-please will wait for a `feat:`/`fix:`/`perf:` commit—or a commit with a `Release-As: 1.0.0` footer—before opening the initial root release PR. **After the first `github-tracker@1.0.0` release PR merges, remove `"release-as": "1.0.0"` from `release-please-config.json` in a `chore(release):` commit** so subsequent releases increment normally from commits. +3. **Merging the Release PR:** When a release PR merges to `main`, `release-please` creates the git tag (`github-tracker@x.y.z` and/or `github-tracker-mcp@x.y.z`), writes `CHANGELOG.md` (and `mcp/CHANGELOG.md`), and publishes the GitHub Release. When `mcp--release_created` is `'true'`, the downstream `publish-mcp` job in `release.yml` checks out the new `github-tracker-mcp@x.y.z` tag, runs `pnpm typecheck`, `pnpm build`, and `pnpm test`, and publishes `github-tracker-mcp` to npm with OIDC provenance (`id-token: write`, no `NPM_TOKEN`). + ## Migration from GitHub App If you previously deployed with the GitHub App model (HttpOnly cookie refresh tokens), follow these steps: diff --git a/README.md b/README.md index 4ba3adb8..7ea6dc5f 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ A dashboard for tracking GitHub issues, PRs, and Actions workflow runs across ma ## Documentation -For detailed feature documentation, see the [User Guide](docs/USER_GUIDE.md). +For detailed feature documentation, see the [User Guide](docs/USER_GUIDE.md). For release history, see [CHANGELOG.md](./CHANGELOG.md). ## Features diff --git a/mcp/README.md b/mcp/README.md index 27c2da21..9c14e70d 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -6,7 +6,7 @@ MCP server for [GitHub Tracker](https://github.com/gordon-code/github-tracker) ```bash # Run without installing -npx github-tracker-mcp +npx github-tracker-mcp@latest # Or install globally npm install -g github-tracker-mcp diff --git a/mcp/src/index.ts b/mcp/src/index.ts index e8711792..83cb72bc 100644 --- a/mcp/src/index.ts +++ b/mcp/src/index.ts @@ -20,7 +20,7 @@ import { RepoRefSchema, TrackedUserSchema } from "../../src/shared/schemas.js"; const server = new McpServer({ name: "github-tracker", - version: "0.1.0", + version: "0.1.1", // x-release-please-version }); // ── Config update validation schemas ────────────────────────────────────────── diff --git a/mcp/tests/version.test.ts b/mcp/tests/version.test.ts new file mode 100644 index 00000000..be58fd6d --- /dev/null +++ b/mcp/tests/version.test.ts @@ -0,0 +1,71 @@ +import { existsSync, readFileSync } from "node:fs"; +import { resolve } from "node:path"; +import { describe, expect, it } from "vitest"; + +const ROOT = resolve(__dirname, "../.."); + +interface PackageJson { + name: string; + version: string; +} + +interface ReleasePleaseManifest { + ".": string; + mcp: string; +} + +interface ReleasePleasePackageConfig { + component?: string; + "extra-files"?: string[]; + "exclude-paths"?: string[]; +} + +interface ReleasePleaseConfig { + packages: { + ".": ReleasePleasePackageConfig; + mcp: ReleasePleasePackageConfig; + }; +} + +function readFile(relPath: string): string { + return readFileSync(resolve(ROOT, relPath), "utf-8"); +} + +function readJson(relPath: string): unknown { + return JSON.parse(readFile(relPath)); +} + +describe("MCP and release-please version synchronization", () => { + it("keeps McpServer version annotated for release-please and synced with mcp/package.json and manifest", () => { + const indexSource = readFile("mcp/src/index.ts"); + const mcpPkg = readJson("mcp/package.json") as PackageJson; + const manifest = readJson(".release-please-manifest.json") as ReleasePleaseManifest; + + const serverBlockMatch = indexSource.match( + /new\s+McpServer\(\s*\{[\s\S]*?version:\s*"([^"]+)",\s*\/\/\s*x-release-please-version[\s\S]*?\}\s*\)/, + ); + + expect(serverBlockMatch).not.toBeNull(); + const serverVersion = serverBlockMatch?.[1]; + expect(serverVersion).toBe(mcpPkg.version); + expect(serverVersion).toBe(manifest.mcp); + }); + + it("keeps root package.json version synced with manifest and registers mcp/src/index.ts in extra-files", () => { + const rootPkg = readJson("package.json") as PackageJson; + const mcpPkg = readJson("mcp/package.json") as PackageJson; + const manifest = readJson(".release-please-manifest.json") as ReleasePleaseManifest; + const config = readJson("release-please-config.json") as ReleasePleaseConfig; + + expect(rootPkg.version).toBe(manifest["."]); + expect(config.packages["."]?.component).toBe(rootPkg.name); + expect(config.packages.mcp?.component).toBe(mcpPkg.name); + expect(config.packages.mcp["extra-files"]).toContain("src/index.ts"); + expect(config.packages["."]["exclude-paths"]).toContain("mcp"); + }); + + it("retires legacy publish-mcp.yml workflow in favor of release.yml", () => { + expect(existsSync(resolve(ROOT, ".github/workflows/publish-mcp.yml"))).toBe(false); + expect(existsSync(resolve(ROOT, ".github/workflows/release.yml"))).toBe(true); + }); +}); diff --git a/release-please-config.json b/release-please-config.json new file mode 100644 index 00000000..1a58bdc6 --- /dev/null +++ b/release-please-config.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", + "release-type": "node", + "include-v-in-tag": false, + "tag-separator": "@", + "include-component-in-tag": true, + "bootstrap-sha": "c63711d42eb125da7be9016a0d853a1cf8c6534d", + "changelog-sections": [ + { "type": "feat", "section": "Features" }, + { "type": "fix", "section": "Bug Fixes" }, + { "type": "perf", "section": "Performance" }, + { "type": "revert", "section": "Reverts", "hidden": true }, + { "type": "docs", "section": "Documentation", "hidden": true }, + { "type": "style", "section": "Styles", "hidden": true }, + { "type": "chore", "section": "Miscellaneous Chores", "hidden": true }, + { "type": "refactor", "section": "Code Refactoring", "hidden": true }, + { "type": "test", "section": "Tests", "hidden": true }, + { "type": "build", "section": "Build System", "hidden": true }, + { "type": "ci", "section": "Continuous Integration", "hidden": true } + ], + "packages": { + ".": { + "component": "github-tracker", + "release-as": "1.0.0", + "exclude-paths": ["mcp"], + "changelog-path": "CHANGELOG.md" + }, + "mcp": { + "component": "github-tracker-mcp", + "changelog-path": "CHANGELOG.md", + "extra-files": ["src/index.ts"] + } + } +} From ca37fe117ebbb891a38938ec872ec1e14bc1628c Mon Sep 17 00:00:00 2001 From: Will Gordon Date: Thu, 5 Nov 2026 15:26:53 -0500 Subject: [PATCH 2/2] ci(release): gate production deploys on app release creation Trigger .github/workflows/deploy.yml via workflow_call from release.yml when release-please cuts a github-tracker@x.y.z release (plus manual workflow_dispatch) instead of on every push to main, so production code, package.json version, and CHANGELOG.md ship atomically. --- .github/workflows/deploy.yml | 11 +++++++++-- .github/workflows/release.yml | 12 ++++++++++++ CONTRIBUTING.md | 2 +- DEPLOY.md | 6 ++++-- mcp/tests/version.test.ts | 11 ++++++++++- 5 files changed, 36 insertions(+), 6 deletions(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index a7016ff6..f3a45818 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -1,7 +1,11 @@ name: Deploy on: - push: - branches: [main] + workflow_call: + inputs: + tag: + description: "Release tag to checkout and deploy" + required: false + type: string workflow_dispatch: permissions: contents: read @@ -10,6 +14,9 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ inputs.tag }} + persist-credentials: false - uses: ./.github/actions/verify with: vite-github-client-id: ${{ vars.VITE_GITHUB_CLIENT_ID }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 258ff062..36bc5af3 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -14,6 +14,8 @@ jobs: contents: read environment: release outputs: + app_release_created: ${{ steps.rp.outputs.release_created }} + app_tag: ${{ steps.rp.outputs.tag_name }} mcp_release_created: ${{ steps.rp.outputs['mcp--release_created'] }} mcp_tag: ${{ steps.rp.outputs['mcp--tag_name'] }} steps: @@ -33,6 +35,16 @@ jobs: config-file: release-please-config.json manifest-file: .release-please-manifest.json + deploy: + needs: release-please + if: github.repository == 'gordon-code/github-tracker' && needs.release-please.outputs.app_release_created == 'true' + permissions: + contents: read + uses: ./.github/workflows/deploy.yml + with: + tag: ${{ needs.release-please.outputs.app_tag }} + secrets: inherit + publish-mcp: needs: release-please if: github.repository == 'gordon-code/github-tracker' && needs.release-please.outputs.mcp_release_created == 'true' diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 19c1cc94..afeafbf5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -120,7 +120,7 @@ Both the root application (`github-tracker`) and the MCP server (`github-tracker - `feat!:` / `fix!:` / `BREAKING CHANGE:` footer bumps the major version - `docs:`, `chore:`, `ci:`, `refactor:`, `test:`, `build:`, `style:`, and `revert:` are hidden from changelog sections - Changes under `mcp/` scope to `github-tracker-mcp`; all other paths scope to `github-tracker` -- **Release PR flow:** When releasable commits land on `main`, `release.yml` opens or updates a release PR that bumps versions and updates `CHANGELOG.md` / `mcp/CHANGELOG.md`. Merging that release PR creates the git tag (`github-tracker@x.y.z` or `github-tracker-mcp@x.y.z`), publishes the GitHub Release, and—when `github-tracker-mcp` is released—publishes the package to npm via OIDC trusted publishing (`release.yml`, environment `npm-publish`). +- **Release PR flow:** When releasable commits land on `main`, `release.yml` opens or updates a release PR that bumps versions and updates `CHANGELOG.md` / `mcp/CHANGELOG.md`. Merging that release PR creates the git tag (`github-tracker@x.y.z` or `github-tracker-mcp@x.y.z`), publishes the GitHub Release, deploys the web application + Worker to Cloudflare (`deploy.yml` via `workflow_call`) when `github-tracker` is released, and publishes `github-tracker-mcp` to npm via OIDC trusted publishing (`release.yml`, environment `npm-publish`) when `mcp` is released. Emergency or out-of-band deployments can still be triggered manually from `main` via `workflow_dispatch` on `deploy.yml`. See [DEPLOY.md](DEPLOY.md#releases) for the maintainer setup (GitHub App permissions, `release` and `npm-publish` environments, npm trusted publisher binding, and tag ruleset). diff --git a/DEPLOY.md b/DEPLOY.md index 049200ac..f16dd3e1 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -257,7 +257,7 @@ pnpm run build wrangler deploy ``` -In CI (`.github/workflows/deploy.yml`), production deployments run `pnpm exec wrangler deploy --tag "$DEPLOY_TAG" --message "$DEPLOY_MSG"` with values passed via `env:` (`DEPLOY_TAG` truncated to 25 characters of `GITHUB_SHA`; `DEPLOY_MSG` taken from the first line of the commit message with ASCII control characters stripped and truncated to 100 UTF-8 characters under `LC_ALL=C.UTF-8`, or `manual deploy ` on `workflow_dispatch`). +In CI (`.github/workflows/deploy.yml`), production deployments are triggered automatically by `.github/workflows/release.yml` (`workflow_call`) when a `github-tracker@x.y.z` release PR merges, or manually via `workflow_dispatch`. The workflow runs `pnpm exec wrangler deploy --tag "$DEPLOY_TAG" --message "$DEPLOY_MSG"` with values passed via `env:` (`DEPLOY_TAG` truncated to 25 characters of `GITHUB_SHA`; `DEPLOY_MSG` taken from the first line of the commit message with ASCII control characters stripped and truncated to 100 UTF-8 characters under `LC_ALL=C.UTF-8`, or `manual deploy ` on `workflow_dispatch`). ## Releases @@ -295,7 +295,9 @@ App (`github-tracker`) and MCP server (`github-tracker-mcp`) releases are automa 1. **Conventional commits on `main` → Release PR:** Every push to `main` triggers `.github/workflows/release.yml`, which mints a short-lived installation token via `actions/create-github-app-token` and runs `googleapis/release-please-action`. Using a GitHub App token (rather than `GITHUB_TOKEN`) ensures `pull_request` CI workflows run automatically on the proposed release PR. 2. **Bootstrap (`1.0.0`) and post-release cleanup:** `release-please-config.json` sets `"bootstrap-sha"` to `c63711d42eb125da7be9016a0d853a1cf8c6534d` and `"release-as": "1.0.0"` on the root `.` package. If only hidden commit types (`ci:`, `chore:`, `docs:`, `test:`, `refactor:`) exist after `bootstrap-sha`, release-please will wait for a `feat:`/`fix:`/`perf:` commit—or a commit with a `Release-As: 1.0.0` footer—before opening the initial root release PR. **After the first `github-tracker@1.0.0` release PR merges, remove `"release-as": "1.0.0"` from `release-please-config.json` in a `chore(release):` commit** so subsequent releases increment normally from commits. -3. **Merging the Release PR:** When a release PR merges to `main`, `release-please` creates the git tag (`github-tracker@x.y.z` and/or `github-tracker-mcp@x.y.z`), writes `CHANGELOG.md` (and `mcp/CHANGELOG.md`), and publishes the GitHub Release. When `mcp--release_created` is `'true'`, the downstream `publish-mcp` job in `release.yml` checks out the new `github-tracker-mcp@x.y.z` tag, runs `pnpm typecheck`, `pnpm build`, and `pnpm test`, and publishes `github-tracker-mcp` to npm with OIDC provenance (`id-token: write`, no `NPM_TOKEN`). +3. **Merging the Release PR:** When a release PR merges to `main`, `release-please` creates the git tag (`github-tracker@x.y.z` and/or `github-tracker-mcp@x.y.z`), writes `CHANGELOG.md` (and `mcp/CHANGELOG.md`), and publishes the GitHub Release: + - When the root `github-tracker` package is released (`release_created == 'true'`), the downstream `deploy` job in `release.yml` invokes `.github/workflows/deploy.yml` (`workflow_call`) at the new `github-tracker@x.y.z` tag, running full verification (`typecheck`, `lint`, `test`, WAF smoke, `test:e2e`), `pnpm validate:deploy`, `pnpm run build`, and `wrangler deploy`. + - When `mcp--release_created` is `'true'`, the downstream `publish-mcp` job in `release.yml` checks out the new `github-tracker-mcp@x.y.z` tag, runs `pnpm typecheck`, `pnpm build`, and `pnpm test`, and publishes `github-tracker-mcp` to npm with OIDC provenance (`id-token: write`, no `NPM_TOKEN`). ## Migration from GitHub App diff --git a/mcp/tests/version.test.ts b/mcp/tests/version.test.ts index be58fd6d..8f952575 100644 --- a/mcp/tests/version.test.ts +++ b/mcp/tests/version.test.ts @@ -64,8 +64,17 @@ describe("MCP and release-please version synchronization", () => { expect(config.packages["."]["exclude-paths"]).toContain("mcp"); }); - it("retires legacy publish-mcp.yml workflow in favor of release.yml", () => { + it("retires legacy publish-mcp.yml workflow in favor of release.yml and gates deploy.yml on releases", () => { expect(existsSync(resolve(ROOT, ".github/workflows/publish-mcp.yml"))).toBe(false); expect(existsSync(resolve(ROOT, ".github/workflows/release.yml"))).toBe(true); + + const releaseYml = readFile(".github/workflows/release.yml"); + const deployYml = readFile(".github/workflows/deploy.yml"); + + expect(releaseYml).toContain("app_release_created: ${{ steps.rp.outputs.release_created }}"); + expect(releaseYml).toContain("uses: ./.github/workflows/deploy.yml"); + expect(deployYml).toContain("workflow_call:"); + expect(deployYml).toContain("workflow_dispatch:"); + expect(deployYml).not.toMatch(/^\s*push:/m); }); });