Skip to content

Releasing

APX implements a PR-first release model: every API change reaches the canonical repository through a pull request that is validated before merge and tagged after merge.

The apx release pipeline is the single path to get an API into the canonical repository. It validates the API, pushes a snapshot to the canonical repo, opens a pull request via the gh CLI, and provides manifest persistence, idempotency checks, catalog updates, and an immutable release record.

The Release Pipeline

  • 1. Prepare

    apx release prepare \
proto/payments/ledger/v1 \
--version v1.0.0-beta.1 \
--lifecycle beta
    Validates schemas, lifecycle policy, version-line compatibility. Writes .apx-release.yaml.

  • 2. Submit

    apx release submit
    Clones the canonical repo, copies the snapshot to a release branch, opens a PR via gh. Idempotent — safe to retry.

  • 3. Finalize

    apx release finalize
    Run by canonical CI after merge: re-validates schemas, creates the official tag, updates the catalog, emits a release record.

See Release Commands for full flag reference and state machine details.

Manifest and Release Record

Every release pipeline run produces two artifacts:

Artifact Created by Purpose
.apx-release.yaml prepare (updated by each phase) Tracks state, identity, validation results, PR metadata
.apx-release-record.yaml finalize Immutable audit record with CI provenance, artifacts, catalog status

Lifecycle Promotions

The release pipeline also supports lifecycle transitions:

# Promote from beta to stable
apx release promote proto/payments/ledger/v1 --to stable --version v1.0.0
apx release submit

# Mark as deprecated
apx release promote proto/payments/ledger/v1 --to deprecated
apx release submit

See Lifecycle Reference for the full lifecycle model.

Validation Pipeline

Every release goes through validation at multiple stages:

  • Pre-Release (Local / App CI)

    • apx lint — schema linting
    • apx breaking — backward compatibility
    • apx semver suggest — version recommendation
    • apx policy check — organizational policy

  • Prepare

    • API ID parsing and identity derivation
    • Lifecycle-version compatibility
    • go_package consistency (proto)
    • go.mod module path validation
    • Idempotency check (SHA-256 content hash)

  • Canonical CI (PR)

    • Re-validates schemas in canonical context
    • Re-checks breaking changes against previous tag
    • Runs policy validation

  • Finalize (Release Pipeline)

    • Re-runs lint and breaking checks
    • Creates annotated git tag
    • Updates catalog
    • Emits release record with CI provenance

See Release Validation for the full validation matrix.

Subdirectory Tagging

APX uses subdirectory-scoped git tags so every API line is versioned independently within a single canonical repository.

<api-id>/v<semver>

Examples:

proto/payments/ledger/v1/v1.0.0-beta.1
proto/payments/ledger/v1/v1.0.0
proto/users/profile/v1/v1.1.0

Tags are created by apx release finalize after the PR is merged.

See Tagging Strategy for full details.

Example: End-to-End Release

1. Validate Locally

apx fetch                          # ensure latest toolchain
apx lint                           # check schema quality
apx breaking --against=HEAD^       # verify backward compatibility
apx semver suggest --against=HEAD^ # get recommended version bump

2. Prepare the Release

apx release prepare proto/payments/ledger/v1 \
  --version v1.2.0 \
  --lifecycle stable

3. Submit to Canonical Repo

apx release submit
# ✓ Pull request created
# PR: https://github.com/acme/apis/pull/42

4. Canonical CI Processes

After the PR is reviewed and merged, canonical CI runs:

apx release finalize

This creates the tag proto/payments/ledger/v1/v1.2.0, updates the catalog, and writes the release record.

Error Handling

Common release errors and solutions:

Error Cause Solution
Version mismatch Tagged version doesn't match suggested Update version to match breaking changes
Breaking change on stable Breaking change with minor/patch bump Use a new major API line (v2)
Policy violation Banned annotation detected Remove service-specific annotations
Lifecycle mismatch Version tag incompatible with lifecycle Use the correct prerelease tag for the lifecycle
gh not found GitHub CLI not installed brew install gh and gh auth login

Best Practices

  • Use apx release for all releases — it provides audit trails, idempotency, and catalog updates
  • Run apx lint and apx breaking before releasing — catch issues early
  • Follow lifecycle conventions — experimental for alpha, beta for beta/rc, stable for GA
  • Coordinate major versions across teams — new API lines (v2) affect all consumers

Next Steps