/gaia-publish

user-facing
Category:
Deployment
Lifecycle phase:
5 -- Deployment / Distribution
Arguments:
--version <semver> [--dry-run] [--skip-verify] [--strict-builtin]

What it does

/gaia-publish is the Phase 5 action command for non-deployable (distribution-only or branch-only) projects. It mirrors /gaia-deploy semantics -- sequential, transparent, no auto-retry, no auto-rollback -- but targets distribution.channel adapters instead of deploy adapters.

The command runs a five-step orchestrator: pre-publish gate, manifest version check, trigger publish, post-publish verify, and final verdict. A failure at any step halts subsequent steps and records the failure in an assessment document.

When a distribution.release_workflow is configured (e.g., a GitHub Actions release workflow), the workflow is the publisher and /gaia-publish awaits and verifies its outcome rather than dispatching a second, competing publish.

When to use it

  • Your project distributes through a registry channel (npm, PyPI, marketplace, container registry, etc.) rather than deploying to an environment.
  • You want to verify that a release workflow completed successfully and the published version is available in the registry.
  • You want a dry-run to validate the publish pipeline without actually pushing to the registry.

Prerequisites

  • A distribution block must exist in .gaia/config/project-config.yaml. Run /gaia-config-distribution add to create one if missing.
  • CI checks must be green on the source branch (the pre-publish gate verifies this).
  • The manifest version must match the --version argument.

How to invoke

/gaia-publish --version 1.5.0
/gaia-publish --version v2.0.0 --dry-run
/gaia-publish --version 1.5.0 --skip-verify
/gaia-publish --version 1.5.0 --strict-builtin

What it does step by step

  1. Pre-publish gate Verifies all required CI checks are green on the source branch. When no checks are configured, the gate passes with a stub-fallback marker.
  2. Manifest version check Reads the file named by distribution.manifest (e.g., package.json, plugin.json), parses the version field, and confirms it matches the --version argument. Leading v is stripped for comparison.
  3. Trigger publish Resolves and dispatches the adapter for the configured distribution.channel. Under --dry-run, the adapter runs in dry-run mode and steps 4-5 are skipped. When a release_workflow is configured, this step awaits the workflow run rather than dispatching an adapter directly.
  4. Post-publish verify Polls the registry via the adapter's verify action with exponential back-off (capped at 3600 seconds). Confirms the published version is available. Bypassed under --skip-verify with a warning.
  5. Final verdict Writes an assessment document to .gaia/artifacts/implementation-artifacts/ with per-step status, detail, and the configuration snapshot. Exit code 0 = PASSED or DRY_RUN; exit code 1 = FAILED.

Inputs

InputSourceDescription
--version <semver>Command argument (required)The version to publish. Must match the version in the distribution manifest.
--dry-runFlag (optional)Run the adapter in dry-run mode. No actual publish occurs; steps 4-5 are skipped.
--skip-verifyFlag (optional)Skip the post-publish registry probe (step 4). Use sparingly.
--strict-builtinFlag (optional)Refuse custom-adapter shadows for sensitive channels (npm, pypi, app-store-connect, etc.).
Distribution config.gaia/config/project-config.yamlThe distribution section: channel, registry, manifest path, and optional release workflow.

Outputs

OutputLocationDescription
Assessment document.gaia/artifacts/implementation-artifacts/assessment-publish-{channel}-{timestamp}.mdPer-step status, failure reasons, and configuration snapshot.

Example session

> /gaia-publish --version 1.5.0

Step 1: Pre-publish gate... PASSED (3/3 checks green on staging @ abc1234)
Step 2: Manifest version check... PASSED (plugin.json = 1.5.0)
Step 3: Trigger publish... OK (marketplace adapter dispatched)
Step 4: Post-publish verify... PASSED (version 1.5.0 found in registry after 12s)
Step 5: Final verdict... PASSED

Assessment written to .gaia/artifacts/implementation-artifacts/assessment-publish-marketplace-2026-10-11T14-30-00.md

Tip: run /gaia-sprint-status to refresh the sprint dashboard with the new release marker.

What to run next

  • /gaia-sprint-status -- refresh the sprint dashboard with the new release marker.
  • /gaia-release -- if you need to bump the version, tag, and push before publishing.

Troubleshooting

this project has no distribution block

The config file has no distribution: section. Run /gaia-config-distribution add to create one.

manifest version <X> does not match --version <Y>

The version in the manifest file does not match the --version argument. Update the manifest (e.g., via /gaia-release) or correct the argument.

pre-publish-gate-failed

One or more required CI checks are red on the source branch. Re-run CI after fixing the failing checks. The error output names the red checks and the HEAD commit SHA.

post-publish-verify-failed

The registry probe could not find the published version within the retry window. Check the adapter output and the registry directly.

HALT: --strict-builtin refuses custom shadow for sensitive channel

A custom adapter shadows a built-in adapter for a sensitive channel (npm, pypi, etc.) and --strict-builtin is active. Remove the custom shadow or drop the --strict-builtin flag if you trust the custom adapter.