diff --git a/standards/ci-cd.md b/standards/ci-cd.md index a062455..5cef946 100644 --- a/standards/ci-cd.md +++ b/standards/ci-cd.md @@ -1,6 +1,6 @@ # CI/CD Standards -Every developer tool repository must have these four core GitHub Actions workflows. Optional workflows are documented at the end. +Cursor-plugin repositories must have the four core GitHub Actions workflows listed below. MCP-server repositories require a different set of three; see MCP-server Variations. Optional workflows are documented at the end. ## Core Workflows @@ -55,49 +55,22 @@ Automatic version bump, tagging, and GitHub Release creation. - `permissions: contents: write` - `fetch-depth: 0` on checkout for full git history -### 3. `pages.yml` +### 3. `drift-check.yml` -**Triggers:** `push` to `main` (paths: `docs/**`, `assets/**`), `workflow_dispatch` +**Triggers:** `push` to `main`, `pull_request` to `main`, `workflow_dispatch` -Deploys the `docs/` directory to GitHub Pages. +Runs the ecosystem drift checker against the repo's own agent files to detect version-signal drift and missing or broken required references. -**Static HTML approach (default):** +**Required configuration:** ```yaml -steps: - - uses: actions/checkout@v4 - - name: Copy assets into docs - run: cp -r assets docs/assets - - uses: actions/configure-pages@v5 - - uses: actions/upload-pages-artifact@v4 - with: - path: docs - - uses: actions/deploy-pages@v5 +- uses: TMHSDigital/Developer-Tools-Directory/.github/actions/drift-check@v1.9 + with: + mode: self + format: gh-summary ``` -**MkDocs approach (for repos with extensive docs):** - -```yaml -steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 - with: - python-version: "3.12" - - run: pip install mkdocs-material - - run: mkdocs build --strict - - uses: actions/upload-pages-artifact@v3 - with: - path: site/ - - uses: actions/deploy-pages@v4 -``` - -**Required permissions:** - -```yaml -permissions: - pages: write - id-token: write -``` +`mode: self` checks only the calling repo's checkout; no cross-repo token is needed. Findings at `info` severity are advisory. Findings at `error` or `warn` severity indicate real drift that should be addressed. ### 4. `stale.yml` @@ -109,12 +82,23 @@ Marks issues and PRs as stale after inactivity and closes them after further ina | Workflow | Purpose | When to include | | --- | --- | --- | +| `pages.yml` | GitHub Pages deployment | Repos with a `docs/` site; generated by scaffold by default | +| `label-sync.yml` | Auto-label PRs by changed file paths | Any repo; generated by scaffold but not required | | `codeql.yml` | Security scanning via GitHub CodeQL | Repos with substantial code (MCP servers, TypeScript packages) | | `dependency-review.yml` | PR dependency audit | Repos with external dependencies | | `release-drafter.yml` | Draft release notes automatically | Repos with frequent PRs | | `ci.yml` | Extended test/lint/build pipeline | Repos with complex test suites | | Domain-specific update | Auto-fetch external data (e.g., native DBs, API schemas) | Repos that consume external data | +## MCP-server Variations + +MCP-server repos require three workflows: `drift-check.yml`, `stale.yml`, and `publish.yml`. This is a different set from cursor-plugin repos, not a superset or subset. + +- **`validate.yml` is not required**. Every check in `validate.yml` (`plugin.json` validity, manifest fields, skill and rule file existence) assumes a `plugin.json`. MCP-server repos have no `plugin.json`, so `validate.yml` does not apply. CI validation is still expected; use `ci.yml` or an equivalent workflow suited to the server's runtime. +- **`publish.yml` replaces `release.yml`**. MCP servers release via npm publish (OIDC provenance recommended; see [versioning.md](versioning.md)). A conventional-commit `release.yml` that reads `plugin.json` does not apply. +- **`pages.yml` is optional**. Include it if the repo has a `docs/` site; omit it otherwise. +- **`drift-check.yml` and `stale.yml` are required**, same as cursor-plugin repos. + ## Workflow Naming - Use lowercase with hyphens: `validate.yml`, `release.yml`, `pages.yml`