Release Process for Automattic/harper: Automated CI/CD Pipeline Explained

The release process for Automattic/harper is a fully automated, test-gated pipeline driven by GitHub Actions and the just task runner, where pushing a versioned Git tag triggers pre-release validation, cross-platform binary compilation, and automated drafting of GitHub releases.

Harper is an open-source grammar and spell checker developed by Automattic. Understanding the release process for Automattic/harper ensures that contributors and maintainers can publish versioned artifacts with confidence, knowing every binary has passed identical quality gates. The repository implements a deterministic, validation-first strategy that prevents broken releases from reaching users.

Pre-Release Validation and Testing

Every push to master and every pull request triggers the pre-release validation suite. The workflow executes just check-js and just check-rust to run the full test matrix across the codebase.

The validation pipeline includes:

• Unit tests for harper-core covering core grammar logic
• Integration tests for each supported platform (Chrome, VS Code, WordPress)
• Playwright web-integration checks for browser compatibility

If any check fails, the workflow aborts immediately, preventing a release from proceeding. This requirement is documented in packages/web/src/routes/docs/contributors/testing-strategy/+page.md under the "Prerelease Checks + Testing" section.

Building Release Artifacts

When a maintainer pushes a new Git tag (e.g., v0.27.0), the Binaries workflow defined in .github/workflows/binaries.yml triggers automatically. The workflow performs the following:

1. Compiles Rust binaries in release mode using cargo build --release (lines 129-135)
2. Executes just tasks (release or release-desktop) to coordinate builds for every target platform: Linux-GNU, Linux-musl, macOS, and Windows
3. Stores executables (harper-cli, harper-ls, etc.) in the target/<target>/release directory structure

The justfile at the repository root defines these build tasks, ensuring consistent compilation flags and target configurations across local development and CI environments.

Publishing GitHub Releases and Plugins

After successful compilation, the pipeline uses ncipollo/release-action to draft a GitHub release and attach the compiled assets. This action creates a draft release (lines 150-153 in binaries.yml) that requires manual maintainer approval before going live.

The same release action is reused across platform-specific plugin workflows:

• Chrome extension: .github/workflows/chrome_plugin.yml (line 43)
• VS Code extension: .github/workflows/vscode_plugin.yml (lines 60-82)
• WordPress plugin: .github/workflows/wp_plugin.yml (line 35)

Each workflow packages its respective plugin, uploads it as a release asset, and associates it with the versioned tag. Maintainers inspect the draft release, optionally edit the auto-generated changelog, and click Publish release to make the artifacts public.

Step-by-Step Release Workflow

To initiate a new release, maintainers follow this exact sequence:

1. Create and push a version tag on the master branch:

git checkout master
git pull
git tag v1.2.3
git push origin v1.2.3

2. GitHub Actions executes the Binaries workflow, building every target platform and creating a draft release titled "v1.2.3".

3. Plugin workflows trigger simultaneously, packaging the Chrome, VS Code, and WordPress extensions and attaching them to the same release.

4. Maintainer review occurs in the GitHub Releases dashboard. After verifying the changelog and attached assets, the maintainer publishes the release.

Local Release Testing

Developers can replicate the CI pipeline locally to verify builds before pushing a tag:

# Run the full pre-release test suite

just check-rust   # Rust unit & integration tests

just check-js     # JavaScript linting and integration tests

# Build all release binaries locally

just release

# Outputs to target/<target>/release/

To manually draft a release without using the automated workflow:

gh release create v1.2.3 ./target/*/release/* \
  --title "Harper v1.2.3" \
  --notes "Changelog details..." \
  --draft

Summary

• Three-stage pipeline: Validation → Build → Publish ensures only tested code reaches users
• GitHub Actions automation: The binaries.yml workflow orchestrates cross-platform compilation using cargo build --release
• Tag-triggered releases: Pushing a version tag to master initiates the entire process
• Multi-platform artifacts: Binaries for Linux, macOS, and Windows attach automatically alongside Chrome, VS Code, and WordPress plugins
• Maintainer gating: Draft releases require manual approval, providing final oversight before publication

Frequently Asked Questions

How do I trigger a new release of Harper?

Push a version tag to the master branch. The GitHub Actions workflows defined in .github/workflows/binaries.yml automatically detect the tag, execute the build pipeline, and create a draft release for maintainer review.

What tests must pass before Harper can be released?

The pre-release validation requires all Rust unit tests (just check-rust), JavaScript integration tests (just check-js), platform-specific integration tests for Chrome/VS Code/WordPress, and Playwright web-integration checks to pass successfully.

Where are the release binaries built in the Harper repository?

The .github/workflows/binaries.yml workflow handles compilation, invoking cargo build --release and storing artifacts in target/<target>/release directories. The justfile defines the specific build tasks for each target platform.

Can I create a Harper release manually without GitHub Actions?

While technically possible using gh release create, the official release process for Automattic/harper requires GitHub Actions to ensure all validation gates execute and cross-platform binaries compile correctly. Manual releases bypass the required test suite and are not recommended.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}