Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 23 additions & 7 deletions .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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 }}
Expand All @@ -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"
35 changes: 0 additions & 35 deletions .github/workflows/publish-mcp.yml

This file was deleted.

67 changes: 67 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -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
4 changes: 4 additions & 0 deletions .release-please-manifest.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
".": "0.1.0",
"mcp": "0.1.1"
}
49 changes: 19 additions & 30 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
42 changes: 42 additions & 0 deletions DEPLOY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <tag>` 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:
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion mcp/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 ──────────────────────────────────────────
Expand Down
80 changes: 80 additions & 0 deletions mcp/tests/version.test.ts
Original file line number Diff line number Diff line change
@@ -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);
});
});
Loading
Loading