diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index e763fc3e..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 }} @@ -29,8 +36,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..36bc5af3 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,67 @@ +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: + 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: + - 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 + + 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' + 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..afeafbf5 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, 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`. -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..f16dd3e1 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -257,6 +257,48 @@ pnpm run build wrangler deploy ``` +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 + +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 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 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..8f952575 --- /dev/null +++ b/mcp/tests/version.test.ts @@ -0,0 +1,80 @@ +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 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); + }); +}); 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"] + } + } +}