Skip to content

CI/CD Pipeline

Workflows

  • ci.yml Runs on pull requests and branch pushes (staging, main) to validate extension code and docs.

  • staging-version-guard.yml Runs on pull requests to staging and blocks release-version changes (extension/manifest.json and docs index version line).
    Version bumping is release-only and must happen from main automation.

  • deploy-docs.yml Runs on staging only when docs-related files change, then builds and deploys MkDocs docs to GitHub Pages. This workflow is docs-only and never bumps extension version.

  • prepare-release.yml Runs on main when extension code changes land. It calculates the next version and opens or updates a release PR against protected main instead of pushing directly. It pushes the release branch directly. The repository should allow GitHub Actions to create pull requests, and REPO_ADMIN_TOKEN remains a fallback if that setting is disabled later.

  • release.yml Runs on main when a release PR merges and extension/manifest.json changes, or by manual dispatch, to:

  • read the manifest version already merged into main
  • create tag vX.Y.Z if it does not exist yet
  • generate friendly GitHub release notes in plain language automatically
  • package extension zip
  • create or update the GitHub release
  • upload + publish to Chrome Web Store API

If the Chrome Web Store item is already under review, the workflow keeps the GitHub release successful and records the store publish as deferred instead of failing the whole release.

  • weekly-staging-to-main.yml Runs weekly (and on manual dispatch) to create/reuse a sync PR from staging to main when staging is ahead. It requests auto-merge and can optionally use admin fallback merge when REPO_ADMIN_TOKEN is configured.

  • apply-branch-protection.yml Manual workflow to apply branch protection policies for main and staging using admin token (REPO_ADMIN_TOKEN).

CI Validation Gates

ci.yml enforces:

  1. node --check on all extension JavaScript files
  2. JSON validation for extension/manifest.json
  3. extension package integrity validation (node scripts/validate-extension.mjs)
  4. junk-file rejection (.DS_Store)
  5. strict MkDocs build (mkdocs build --strict)

Chrome Web Store Publish Flow

  1. Merge cycle promotes code from staging to main.
  2. prepare-release.yml computes the next semantic version automatically.
  3. prepare-release.yml opens or updates a release PR to protected main.
  4. CI runs on the release PR branch.
  5. After approval and merge, release.yml creates and pushes tag v<version>.
  6. release.yml publishes the GitHub Release with friendly autogenerated release notes.
  7. release.yml packages extension zip in dist/.
  8. release.yml uploads extension package to Chrome Web Store API.
  9. release.yml publishes uploaded package (default target unless overridden by CWS_PUBLISH_TARGET).

Required Secrets

  • CWS_CLIENT_ID
  • CWS_CLIENT_SECRET
  • CWS_REFRESH_TOKEN
  • CWS_PUBLISHER_ID
  • CWS_EXTENSION_ID
  • optional CWS_PUBLISH_TARGET
  • optional REPO_ADMIN_TOKEN (recommended for release PR creation, branch-protection apply, and weekly admin merge fallback)