Skip to content

ci-cd.md

Latest commit

 

History

History
128 lines (94 loc) · 4.28 KB

ci-cd.md

File metadata and controls

128 lines (94 loc) · 4.28 KB

CI/CD Standards

Every developer tool repository must have these four core GitHub Actions workflows. Optional workflows are documented at the end.

Core Workflows

1. validate.yml

Triggers: push to main, pull_request to main

Validates the structural integrity of the plugin before merging.

Required checks:

Check Description
JSON validity plugin.json (and mcp.json if present) parse without errors
Manifest fields All required fields exist, name is kebab-case
Skill file existence Every path in plugin.json skills array points to a real file
Rule file existence Every path in plugin.json rules array points to a real file
Frontmatter Skills have YAML frontmatter starting with ---; rules have .mdc frontmatter
Credential scanning No hardcoded passwords, API keys, or tokens in source files

Conditional checks (include if applicable):

Check Condition
Python syntax If mcp-server/ exists, py_compile all .py files
Test suite If tests/ exists, run pytest tests/ -v
Content counts If README contains stat counts, verify they match actual file counts

2. release.yml

Triggers: push to main (with paths-ignore for docs, markdown, and .github/ changes)

Automatic version bump, tagging, and GitHub Release creation.

Flow:

  1. Read current version from .cursor-plugin/plugin.json
  2. Parse commit messages since last tag for bump type:
    • feat!: or BREAKING CHANGE = major
    • feat: = minor
    • Everything else = patch
  3. Compute new semver version
  4. Update plugin.json version and README.md version badge
  5. Commit with chore: bump version to X.Y.Z [skip ci]
  6. Create git tag vX.Y.Z
  7. Create GitHub Release with grouped release notes
  8. Sync repo About section (description, homepage, topics) via gh repo edit

Requirements:

  • concurrency: { group: release, cancel-in-progress: false } to prevent race conditions
  • permissions: contents: write
  • fetch-depth: 0 on checkout for full git history

3. pages.yml

Triggers: push to main (paths: docs/**, assets/**), workflow_dispatch

Deploys the docs/ directory to GitHub Pages.

Static HTML approach (default):

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

MkDocs approach (for repos with extensive docs):

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:

permissions:
  pages: write
  id-token: write

4. stale.yml

Triggers: schedule (daily or weekly), workflow_dispatch

Marks issues and PRs as stale after inactivity and closes them after further inactivity. Use actions/stale with sensible defaults (e.g., 30 days stale, 7 days to close).

Optional Workflows

Workflow Purpose When to include
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

Workflow Naming

  • Use lowercase with hyphens: validate.yml, release.yml, pages.yml
  • The name: field inside the workflow should be title case: Validate, Release, Deploy GitHub Pages
  • Job names should be descriptive: validate-json, bump-version-and-release, deploy

Secrets and Permissions

  • Use ${{ secrets.GITHUB_TOKEN }} (automatically provided) for all Git operations
  • Never store custom secrets unless absolutely required (e.g., npm publish tokens)
  • Set minimal permissions at the workflow level, not at the job level