MARS Developer docs

Shipping and drift

Update the command, update deployed harnesses, and prepare verifiable releases.

MARS uses repo-owned semantic versions, generated changelog entries, target harness version metadata, signed archive CLI updates, local release evidence, and separately gated GitHub Releases. This guide separates day-to-day user updates from source maintainer snapshot preparation and approved cutover.

Release evidence: release notes, private snapshots, checksums, and verification are part of the current audit trail; tags and remote assets join it only after publication is authorized. Use validation and evidence when you need the canonical proof path.

Version Files

Source and initialized target repos both use a root VERSION and CHANGELOG.md. Source releases also update internal/buildinfo/version.go so local source-tree builds report the same version. For ownership rules around generated assets, use the Files And State Reference.

FileWhereUser purpose
VERSIONSource and targets.Repo-owned semantic version source.
CHANGELOG.mdSource and targets.Generated patch notes with Impact, Why, and What Changed sections.
internal/buildinfo/version.goMARS source only.Fallback version for source-tree builds when release ldflags are absent.
.harness/metadata.yamlTarget repos.Generated harness version drift signal.
dist/MARS source rehearsal work.Four archives, four SBOMs, checksums, and temporary producer state. Only the exact publishable allowlist is candidate evidence; the directory itself proves nothing.

Update Check

Use mars update check to see whether the installed tool or a deployed target harness is behind. Remote release lookup failures are reported as unknown so local target checks can still complete.

Check a target

mars update check --repo ~/my-project
mars update check --repo ~/my-project --json

Skip remote release lookup

mars update check --repo ~/my-project --skip-remote

Use a custom latest-release endpoint

mars update check \
  --repo ~/my-project \
  --latest-release-url https://api.example.invalid/repos/org/project/releases/latest

Tool Update

mars update tool has source and packaged modes. Release mode accepts only the canonical signed archive contract: it verifies the offline Sigstore bundle over the exact checksum bytes, immutable tag/full commit, platform/build metadata, archive digest and structure, then durably replaces or restores the fixed binary. Source checkout update is the current supported route; packaged availability stays blocked until the approved F-018 cutover release.

PathCommandUse when
Source checkoutmake update-toolCurrent supported route from a clean clone; fast-forward and reinstall the checked source.
First exact signed installscripts/install.sh vX.Y.Z /absolute/install/dirImplemented but unusable until an approved exact signed tag exists. Requires stable Go 1.25.13+ once, an independently reviewed checkout at the same tag, and an existing owner-controlled directory.
Packaged dry runmars update tool --dry-runUse only after an approved signed release exists; previewing never grants installation authority.
Latest signed releasemars update toolBlocked until F-018 cutover publishes the exact signed archive contract.
Specific signed releasemars update tool --version vX.Y.ZRequires that exact approved signed contract; historical raw assets are unsupported.
Source installmars update tool --sourceUse Go source installation instead of release assets.
Main branch sourcemars update tool --version mainSource-development update path for users who intentionally track main.
Source checkout users: make install installs the current checkout. Use make update-tool from a clean clone when you want the source-maintained update helper to fast-forward, reinstall, and run path setup. Regenerate completions separately when you want updated shell tab completion scripts.
Bootstrap trust boundary: run the repository-owned shell script only from an independently reviewed checkout at the same exact stable tag; piping a network-fetched script directly into a shell is unsupported. Execute ./scripts/install.sh directly; an explicit shell-interpreter invocation fails closed so the privileged Bash shebang can suppress inherited functions and BASH_ENV. Its clean body preserves only PATH, HOME, and TMPDIR; optional GitHub tokens cross through dedicated descriptors, remain absent from Go, and enter only the staged signed updater. The script resolves one absolute Go executable, disables Go auth and CGO, neutralizes inherited build controls, applies -modcacherw, and builds the canonical Go module through the public Go proxy and SumDB in owner-only temporary staging. The staged command validates its own running command/module, exact tag, canonical SHA-256 h1 sum, and lack of replacements before invoking the signed updater with the same tag and final directory. Archive, checksum, signature, and durable replacement authority stay entirely inside that updater; the bootstrap handoff skips ordinary shell-profile mutation. Pre-commit rejection leaves an existing destination unchanged. A recovery-required result instead requires preserving transaction evidence and repairing from the reviewed checkout before retrying.

Harness Update

mars update harness fills in missing generated defaults in a target repo. It preserves target-owned manifests, role prompts, guardrails, skills, knowledge routes, tickets, plans, design docs, references, and release state.

Update missing defaults

mars update harness --repo ~/my-project
mars upgrade --repo ~/my-project

upgrade and update harness use the same user-facing intent.

Review generated drift

git -C ~/my-project status --short
git -C ~/my-project diff

Generated additions belong to the target repo after review.

Release Auth

Official release metadata is anonymous-first. Ordinary source checkout install uses mars setup without GitHub credentials. Optional auth can grant access for private forks or a GitHub rate-limit fallback. It does not authorize publication or prove artifact authenticity. For the full credential map, open the Authentication And Credentials Reference.

Ordinary public check

mars auth github check --json

The command makes one exact, no-redirect anonymous request to the official api.github.com release-metadata endpoint. Only an exact 401, 403, or 404 may resolve credentials and retry the same origin and path once.

Headless setup

export GH_TOKEN=...
mars auth github check --json

Token values must not be committed, printed in logs, pasted into docs, or included in traces.

Persist an owner-only fallback

mars auth github setup --token "$GH_TOKEN"

Prefer GitHub CLI auth when possible. The local fallback belongs under ~/.mars/, never in a repo.

Remove only the local fallback

mars auth github clear-local

This leaves environment variables, GitHub CLI and GitHub App credentials, repositories, and remote state unchanged.

The check reports anonymous, authenticated, or unavailable without revealing credential-derived information.

Release Notes

Release notes are generated from semantic commits and should explain user-facing impact. The generator ignores release: commits so the release-note commit does not create an infinite loop.

Preview notes

mars release notes --repo . --bump auto --dry-run

Generate notes

mars release notes --repo . --bump auto
mars release backfill-notes --repo . --check

Backfill historical narrative if required

mars release backfill-notes --repo . --dry-run
mars release backfill-notes --repo .
mars release backfill-notes --repo . --check

MARS Source Release Flow

Source maintainers have an extra binary production gate. During T-065 through T-068, MARS retains the 0.68.49 version floor and records validated semantic checkpoints plus publication-disabled snapshot evidence. Tags, signatures, uploads, announcements, and a supported-release claim require the separately approved cutover.

  1. Commit the semantic change

    git commit -m "docs(site): expand release documentation"

  2. Generate and commit release notes

    mars release notes --repo . --bump auto
mars release backfill-notes --repo . --check
git add VERSION CHANGELOG.md internal/buildinfo/version.go
git commit -m "release: notes X.Y.Z"

  3. Push the validated checkpoint

    git push origin main

    Tags and publication remain separately gated by F-017/F-018.

  4. Build and verify no-publish release evidence

    Run the conventional Go/Syft production and verification rehearsal authorized by AD-315 before tagging. The T-080 workflow is tag-only and least privilege; the rehearsal itself does not tag, upload, attest, announce, or publish.

Target Repo Release Flow

Initialized target repos inherit semantic versioning and generated patch notes, but they do not inherit MARS source binary publication. Target release publication depends on the target product's own deployment model.

Generate target notes

mars release notes --repo ~/my-project --bump auto
mars release backfill-notes --repo ~/my-project --check

Commit target release state

git -C ~/my-project add VERSION CHANGELOG.md
git -C ~/my-project commit -m "release: notes X.Y.Z"
git -C ~/my-project push origin main

Assets And Verification

MARS source uses the conventional AD-315/F-018 Go/Syft/GitHub-attestation workflow. Generated target repositories choose and document their own producer and verifier. The standalone verifier and audit commands are retired. Remote transport success is not completion, and unavailable or unverifiable state stays blocked.

SurfaceGateWhat success proves
Repository-approved producerBuild/package contractFor MARS source, the no-publish rehearsal produces four archives, four SBOMs, and checksums.txt without publication authority. Targets define their own equivalent contract.
F-018 signed archive consumerAuthenticity and safe replacementSignature, workflow identity, immutable commit, platform/build metadata, checksum, archive, and durable transaction all pass.
Repository-owned remote gateIdentity and inventory convergenceThe repository-approved artifacts exactly match the immutable release; MARS source specifically requires F-018 signed identity. Missing, partial, inaccessible, or unverifiable state is blocked.
gh release view vX.Y.ZTransport inspection onlyA Release object can be observed; this alone proves neither authenticity nor completion.

Recipes

Upgrade a target safely

mars update check --repo ~/my-project --json
mars update harness --repo ~/my-project
mars doctor --repo ~/my-project --json

Update a source checkout install

make update-tool
mars version

Inspect a future approved source release

gh release view vX.Y.Z --repo greaveselliott/MARS

Then run the approved F-018 remote-convergence gate; the listing alone is not completion evidence.

Troubleshooting

SymptomLikely causeUser action
update check reports remote unknown.Latest-release API could not be reached or auth is missing.Use --skip-remote for local drift checks, or run mars auth github check.
An approved signed update tool run cannot download private assets.No valid private release auth source.After confirming the approved signed release exists, run gh auth login, then mars auth github setup, or set GH_TOKEN/GITHUB_TOKEN.
Release notes sound generic.The semantic commit lacks explicit Impact, Why, or What details.Polish the top changelog entry before committing release notes.
Local asset verification fails.The producer output is incomplete or does not satisfy the repository artifact contract.Rerun the repository-approved producer and its contract check. For MARS source, use the publication-disabled F-018 snapshot workflow.
GitHub release is notes-only.The tag/release object exists but its artifact set is incomplete.Treat publication as blocked and use the separately approved repository release workflow; the retired MARS producer cannot repair it.
mirror_incomplete is reported.The remote release is partial, extra, pending, mismatched, or unverifiable.Preserve immutable refs, inspect the reported classifications, and keep publication blocked until an approved workflow proves exact convergence.