Canonical Pull Request¶

apx release submit opens a pull request against the canonical repository (github.com/<org>/apis). This page describes the end-to-end flow.

Prerequisites¶

Requirement	How to satisfy
`gh` CLI installed	`brew install gh` or cli.github.com
`gh` authenticated	`gh auth login`
Push access to canonical repo	Org admin grants write or maintainer role

Flow¶

App repo                          Canonical repo
────────                          ──────────────
 1. apx release prepare
    (validate, write manifest)

 2. apx release submit
    ├─ shallow-clone canonical
    ├─ checkout -b apx/release/<api>/<ver>
    ├─ copy module files
    ├─ generate go.mod (if missing)
    ├─ git commit + push
    └─ gh pr create ───────────►  PR opened
                                   │
                                   ▼
                                  3. Canonical CI validates
                                     (lint, breaking, policy)
                                   │
                                   ▼
                                  4. Reviewer merges PR
                                   │
                                   ▼
                                  5. apx release finalize
                                     (tag, catalog, release record)

Branch Naming¶

Feature branches follow the pattern:

apx/release/<api-id-dashes>/<version>

For example, apx/release/proto-payments-ledger-v1/v1.0.0-beta.1.

PR Metadata¶

Field	Value
Title	`release: <api-id>@<version>`
Body	`Automated release of API \`` at version ``.`
Base	`main`
Head	the feature branch above

What Gets Committed¶

The PR contains the module's source files copied from the app repo into the canonical path. For a proto API proto/payments/ledger/v1, the PR diff shows changes under proto/payments/ledger/:

proto/payments/ledger/
├── go.mod          ← generated if missing
└── v1/
    └── ledger.proto

Example¶

# From your app repo
apx release prepare proto/payments/ledger/v1 \
  --version v1.0.0-beta.1 \
  --lifecycle beta

apx release submit

# Output:
#   Submitting release proto/payments/ledger/v1 @ v1.0.0-beta.1
#   ✓ Release submitted successfully
#   PR: https://github.com/acme/apis/pull/42

Troubleshooting¶

"gh CLI not found"¶

Install the GitHub CLI: brew install gh or see cli.github.com.

"gh is not authenticated"¶

Run gh auth login and follow the prompts.

"permission denied" on push¶

You need write access to the canonical repo. Ask an org admin to grant you the Write or Maintainer role on the repo.

"no changes to release"¶

The canonical repo already contains identical content for this module. Verify you have new changes to release.