release-process.mdx

title	Release process
description	Evidence required before publishing a Copilot release.

Release process

1. Confirm the candidate branch and working tree.
2. Review source, generated bundles, workflows, action.yml, npm package metadata, and MDX navigation.
3. Run all quality, package, and documentation gates.
4. Review the diff for credentials, retired inputs, implicit defaults, unauthorized fallback, and files that must not enter the npm tarball.
5. Confirm the release version will be identical in package.json, the Git tag, the GitHub release, and npm.
6. Commit with a specific message.
7. Push explicitly to the intended branch.
8. Verify local and remote SHAs match and the working tree is clean.

npm package

The CLI is published as the public scoped package @vypdev/copilot. The package exposes the global copilot executable and includes the compiled Action and CLI bundles, action.yml, and the setup templates needed by copilot setup.

Before publishing locally, validate the package contents:

corepack pnpm run build
corepack pnpm run validate:npm-package
corepack pnpm run smoke:npm-package
corepack pnpm run validate:documentation

The project release_workflow.yml coordinates npm publishing with the rest of the release. It first promotes the frozen release branch to production through a GitHub-managed PR. After that PR merges, the continuation creates the version tag at the accepted production SHA, publishes that exact tag to npm on a GitHub-hosted runner, creates the GitHub Release, updates the major GitHub Action reference, and begins development reconciliation:

prepare release -> production PR -> accepted production SHA
  -> create tag -> publish npm -> finalize GitHub release
  -> production-to-development reconciliation -> close issue

For unattended completion, enable repository auto-merge and active required validation on both production and development targets. This repository requires GitHub Actions CI Check on master and develop; RepoWise is optional and runs only through manual dispatch. Default auto mode enables native auto-merge while a managed PR must wait. When GitHub already reports the PR ready, Copilot requests a normal merge pinned to its verified head SHA. This also handles pending advisory checks, without bypassing branch rules. A moved head or failed readiness read blocks safely and preserves the operation for retry. Verify that both promotion and reconciliation merged automatically before reporting an unattended release as complete.

If GitHub rejects a merge because readiness changed since the inspection, Copilot rechecks the same PR, frozen head, and current target rules once. It then applies a different permitted automatic action, such as enabling native auto-merge while required CI starts. A second rejection or unchanged decision blocks the operation. Permission errors and head conflicts never trigger this recovery. Both direct merge and native enablement include the expected head. Failure details retain the attempted action and a sanitized error category; unclassified failures do not claim a GitHub outage.

If publication is already verified and reconciliation setup failed, use the workflow's resume mode with the stored issue, operation ID, and version. It rechecks publication receipts and configures the existing PR without publishing npm again. See recovery by visible phase.

The npm job installs the frozen dependency graph before validating and smoke-testing the package. After publishing, it waits until npm view exposes the exact version, polling every 20 seconds for up to 10 minutes by default. Each lookup is limited to the remaining time, and responses arriving after the deadline are rejected. It then verifies that the registry gitHead is the accepted production commit. It uses npm trusted publishing with these least-privilege permissions:

permissions:
  contents: read
  id-token: write

The npm package must be configured to trust this repository and workflow before automated publication. Configure trusted publishers for organization vypdev, repository copilot, environment npm, and both publishing workflow filenames: release_workflow.yml and hotfix_workflow.yml. Enter only the exact, case-sensitive filename including its extension. For both connections, Allowed actions must permit direct npm publish; new npm publisher configurations may otherwise allow only staged publishing. The job publishes with npm publish --access public; trusted publishing generates provenance automatically and does not store an npm token in the repository.

npm trusted publishing requires npm CLI 11.5.1 or newer, Node 22.14.0 or newer, a GitHub-hosted runner, id-token: write, and a package.json.repository.url that exactly matches the GitHub repository. Node 24 on ubuntu-latest satisfies the runtime minimum. npm whoami cannot validate this OIDC path ahead of time, because authentication is exchanged during the publish command. See the npm Trusted Publishing reference.

The visibility wait is configured with Repository Variables:

Variable	Default	Allowed range
NPM_VISIBILITY_POLL_INTERVAL_SECONDS	20 seconds	10–60 seconds
NPM_VISIBILITY_TIMEOUT_SECONDS	600 seconds (10 minutes)	60–900 seconds

Before testing the lifecycle, the new release, hotfix, and copilot_deployment_orchestration.yml workflow files must all be present on master. The continuation relies on pull_request: closed, and GitHub resolves event and dispatch workflows through the default/base branch. See the GitHub Actions event reference.

The repository-specific workflow is intentionally not copied to setup/workflows: consumers of the action do not publish @vypdev/copilot when running their own release workflows.

For branch origins, merge modes, recovery, and repository setup, see Release and hotfix orchestration.

To verify a published version independently:

npm view @vypdev/copilot version
pnpm add --global @vypdev/copilot@<version>
copilot --version

A release MUST NOT be described as complete without current command output proving these steps.