Publishing step by step
Plans, verification, transactions, status, resume and abort
gritpack publish does everything in one go: it plans, verifies, asks, and
publishes. That is right most of the time. But when you release several
packages that depend on each other, or when a release goes through review or
CI, you want the steps apart: build a plan, look at it, have the hub check it,
and only then publish, knowing that either every package appears or none does.
The gritpack publication commands are those steps. This chapter publishes two
packages, one depending on the other, and then shows what happens when a
publication is interrupted.
What you will be able to do
- write a publication plan for several packages and read it;
- have the hub verify a plan without changing anything;
- publish a plan so that all its packages appear together, or none do;
- check on a publication, finish an interrupted one, or cancel it;
- keep plans and built files where your release process wants them.
Two packages, one release
Here are two C packages in one repository. @ada/report depends on
@ada/core:
release/
core/gritpack.toml name = "@ada/core", version = "1.0.0"
report/gritpack.toml name = "@ada/report", version = "1.0.0"
[dependencies] "@ada/core" = "^1.0.0"
Publishing them separately has an awkward moment: after core is out but
before report is, the hub holds half a release. If the second publication
fails, the half stays. A publication plan avoids that: both packages go into
one transaction, and the hub makes them visible together.
First, tell Gritpack the two directories belong together. gritpack workspace init finds the packages and writes gritpack-workspace.toml:
$ gritpack workspace init
workspace . members=2 status=created
member=core adapter=Native role=Publishable
member=report adapter=Native role=Publishable
Workspaces covers workspaces properly. For this chapter, all that matters is that Gritpack now sees one release with two members.
Step 1: plan
A plan is built on your machine and changes nothing anywhere else. It needs
to know which hub it is for, by the hub's repository ID. gritpack publish --dry-run prints it on the verification line (repository=...), and so does
gritpack evidence root:
$ gritpack publication plan --repository 550e8400-e29b-41d4-a716-446655440000
local publication planning performs no registry mutation; Go members are packaged without execution, while Cargo members may run cargo metadata/package and rustc version checks with the recorded flags
publication plan=sha256:aacb167b... result=RequiresRemoteVerification nodes=2 edges=1 output=./.gritpack/publication-plan.json
native:@ada/core@1.0.0:c/c23:-:- adapter=Native status=Indeterminate artifact=.gritpack/publication/artifacts/...
check=PUBLICATION_METADATA_COMPLETE status=Passed — gritpack.toml declares description, README, licence
check=PUBLICATION_DOCUMENTATION_POLICY status=Passed — README and licence meet the hub's documentation policy
check=PUBLICATION_LICENSE_DECLARED status=Passed — MIT
native:@ada/report@1.0.0:c/c23:-:- adapter=Native status=Indeterminate artifact=.gritpack/publication/artifacts/...
@ada/core ^1.0.0 -> publication-set status=Internal
check=PUBLICATION_METADATA_COMPLETE status=Passed — gritpack.toml declares description, README, licence
check=PUBLICATION_DOCUMENTATION_POLICY status=Passed — README and licence meet the hub's documentation policy
check=PUBLICATION_LICENSE_DECLARED status=Passed — MIT
The plan has two nodes, one per package, and one edge: report's
dependency on core is satisfied inside this same publication
(publication-set status=Internal), so core is published first. Each node's
ID spells out the package's full identity:
native:@ada/core@1.0.0:c/c23:-:- is the ecosystem, the name and version, the
dialect, and the encoding and target (- when there is none).
Gritpack built both package files into .gritpack/publication/artifacts/ and
wrote the plan to .gritpack/publication-plan.json. The plan records each
file's SHA-256, and its own digest (plan=sha256:...) identifies it exactly.
result=RequiresRemoteVerification is expected: only the hub can say whether
you own the names and whether the versions are free.
Where things go is yours to choose, relative to the workspace root:
gritpack publication plan --repository <repository-id> \
--plan release/plan.json --artifacts-dir release/artifacts
--member core limits a plan to some members, and --without-readme and
--without-license work here as in README and licence.
For Cargo and Go members, plan also takes the options described in
Rust and Cargo and Go modules.
Step 2: verify
gritpack publication verify checks the files against the plan, then sends
the plan to the hub for checking. Nothing is reserved or uploaded:
$ gritpack publication verify .gritpack/publication-plan.json
publication verification plan=sha256:aacb167b... repository=550e8400-e29b-41d4-a716-446655440000 result=Publishable generation=sha256:af35bace... attestation_threshold=0
native:@ada/core@1.0.0:c/c23:-:-: New
PUBLICATION_AUTHORITY_VERIFIED: Passed: publisher owns the package authority
native:@ada/report@1.0.0:c/c23:-:-: New
PUBLICATION_AUTHORITY_VERIFIED: Passed: publisher owns the package authority
Each node gets one of four answers:
- New: the version is free and will be published.
- Satisfied: exactly this file is already published under this version. Publishing again changes nothing, which makes re-running a release safe.
- Conflict: the version exists with different content. Raise the version.
- Blocked: a rule failed, such as a missing README, a licence rule, or a name you do not own. The failed check says which.
result=Publishable means every node is New or Satisfied.
Verification also rehashes every built file. If a file changed after planning, by accident or otherwise, verification stops before talking to the hub, with exit code 7 (integrity):
$ gritpack publication verify .gritpack/publication-plan.json
publication plan could not be canonicalized: artifact changed after planning: .gritpack/publication/artifacts/...
Plan again to pick up a deliberate change.
For automation. This split is made for review. A CI job can run
plan, keeppublication-plan.jsonand the built files as job outputs, runverify, and let a person approve before a later job runspublishon the exact same files. The plan's digest proves they are the files that were reviewed.
Step 3: publish
$ gritpack publication publish .gritpack/publication-plan.json
committed publication transaction=01a1e86b-6ab4-7912-8e67-7bd211b65cf6 plan=sha256:aacb167b... generation=sha256:1bc3501d... nodes=2
native:@ada/core@1.0.0:c/c23:-:-: New storage_id=01M7M6PTNMF498WSVVW1EH76TP digest=sha256:0cf9dc527416627a278e53444d93d978de9f85d0257175342704c82a7e6c51be
native:@ada/report@1.0.0:c/c23:-:-: New storage_id=01M7M6PTNMF498WSVVZRCH23SJ digest=sha256:91427d7f29c6e5e6ce05c6c21dde35f83cb04ada530a4cf9005959a2314c52cc
publication publish does not ask for confirmation: running it is the
decision. Behind that one command:
- The hub opens a transaction for this plan and your login.
- Gritpack uploads ("stages") each new package file. The hub checks each one itself. Staged packages are invisible: searches, installs and downloads do not see them.
- The hub verifies the whole set again.
- The hub commits: one record makes every package in the transaction visible at the same moment. Anyone reading the hub sees all of the release or none of it.
- Gritpack prints the receipt. Its transaction ID is also the ID of the hub's signed receipt (Evidence and receipts).
Publishing the same plan again is safe. The hub recognises the plan and your login, and returns the transaction it already has: if it was committed, you get the same receipt; if it was part way, publishing continues where it stopped and uploads only what is missing.
From Cargo.
cargo publishpublishes one crate at a time, so a workspace release can stop half way. A plan of Cargo crates on a Gritpack hub commits them together. Cargo still builds and checks each crate itself.
Machine-readable reports
Every publication command takes --format json or --format ndjson.
NDJSON prints one JSON record per line: the plan, then each node, each edge,
and each observation. Here is the plan for the next release, 1.1.0, with the
long records shortened:
$ gritpack publication plan --repository 550e8400-e29b-41d4-a716-446655440000 --format ndjson
{"destination":{...},"output":"./.gritpack/publication-plan.json","plan_digest":"sha256:5c5ec84c...","publication_order":["native:@ada/core@1.1.0:c/c23:-:-","native:@ada/report@1.1.0:c/c23:-:-"],"result":"requires_remote_verification","schema":"gritpack/publication-report@1","type":"plan"}
{"node":{...,"identity":{"dialect":"c/c23","name":"@ada/core","version":"1.1.0"},"node_id":"native:@ada/core@1.1.0:c/c23:-:-",...},"schema":"gritpack/publication-report@1","type":"node"}
{"node":{...,"node_id":"native:@ada/report@1.1.0:c/c23:-:-",...},"schema":"gritpack/publication-report@1","type":"node"}
{"edge":{"dependency":"@ada/core","from":"native:@ada/report@1.1.0:c/c23:-:-","to":"native:@ada/core@1.1.0:c/c23:-:-"},"schema":"gritpack/publication-report@1","type":"edge"}
{"observation":{"code":"PUBLICATION_REMOTE_VERIFICATION_REQUIRED","detail":"authority, occupied identities, registry policy, and external prerequisites were not checked","status":"unverified"},"schema":"gritpack/publication-report@1","type":"observation"}
Branch on the code and status fields, not on the human text. The receipt
from publication publish --json lists each node with its node_id,
disposition (new or satisfied) and storage_id.
When a publication is interrupted
A laptop closes, a network drops, a CI job is cancelled. The transaction is then left open on the hub, holding whatever was staged, and nothing is visible. To make one on purpose while releasing 1.2.0, move one of the built files away before publishing:
$ gritpack publication publish .gritpack/publication-plan.json
failed to read ./.gritpack/publication/artifacts/...: No such file or directory (os error 2)
That stopped with exit code 9 (a local file problem), after the hub had opened the transaction. Nothing became visible:
$ gritpack info @ada/core
@ada/core 1.1.0 (native)
...
versions: 1.1.0, 1.0.0
You have three choices.
Publish the same plan again. This is the usual answer. The hub hands back
the open transaction, Gritpack uploads what is missing, and the hub commits.
Put the file back (or plan again: packing is deterministic, so the file comes
out the same) and run gritpack publication publish once more.
Look at it. Gritpack prints the transaction ID only with the receipt, so an interrupted run does not show it, and there is no command to list open transactions. Publishing the plan again is therefore the usual way on. When you do have an ID, you can ask about it:
$ gritpack publication status 01a1e86c-fcac-7562-9648-75813123e39a
publication transaction=01a1e86c-fcac-7562-9648-75813123e39a state=Created plan=sha256:8d5b4c20... nodes=2 expires_at=1794904419
state is one of:
| State | Meaning |
|---|---|
Created | opened, staging not finished |
Ready | every package staged and checked; ready to commit |
Committing | commit under way |
Committed | done; everything visible |
Aborted | cancelled; nothing became visible |
An open transaction expires an hour after it was opened (expires_at, in Unix
seconds). An expired or cancelled transaction's staged files are kept for a
day and then removed.
gritpack publication resume finishes a transaction that is Ready or
Committing, for example when the connection dropped during the commit. It
does not stage anything, so for a Created transaction it says to publish the
plan again:
$ gritpack publication resume 01a1e86c-fcac-7562-9648-75813123e39a
publication verification protocol failed: publication transaction 01a1e86c-fcac-7562-9648-75813123e39a is Created; only a ready or committing transaction can be resumed. Publish the same plan again to continue staging it
Cancel it. gritpack publication abort closes a transaction that has not
begun committing. The versions it held become free again:
$ gritpack publication abort 01a1e86c-fcac-7562-9648-75813123e39a
publication transaction=01a1e86c-fcac-7562-9648-75813123e39a state=Aborted
$ gritpack publication abort 01a1e86c-fcac-7562-9648-75813123e39a
abort publication transaction: the hub answered HTTP 409: publication transaction is already closed
After an abort, publishing the same plan opens a new transaction:
$ gritpack publication publish .gritpack/publication-plan.json
committed publication transaction=01a1e86d-326a-7e13-88a3-69d06b455d80 plan=sha256:8d5b4c20... generation=sha256:cec6a46d... nodes=2
...
A committed transaction cannot be aborted. Once it is visible, the versions are published, and After publishing applies.
Under the hood. The commit record is the single switch that makes a transaction's packages visible. A hub that restarts during a commit finishes it when it starts again, or marks it for recovery without making anything visible. Readers never see half a release.
The short form, revisited
gritpack publish in a workspace runs these same three steps:
gritpack publish --dry-run # plan + verify
gritpack publish --yes # plan + verify + publish
It takes the plan options too (--plan, --artifacts-dir, --member), and
finds the hub's repository ID by itself:
$ gritpack publish --dry-run --plan release/plan.json --artifacts-dir release/artifacts
...
publication plan=sha256:e218c497... result=RequiresRemoteVerification nodes=2 edges=1 output=./release/plan.json
...
native:@ada/core@1.2.0:c/c23:-:-: Satisfied
native:@ada/report@1.2.0:c/c23:-:-: Satisfied
dry run complete; registry was not mutated
Use the separate commands when someone or something needs to stand between the steps.
What just happened
publication planbuilt every package file and wrote a plan with their digests and the order to publish them, changing nothing on any hub.publication verifychecked the files against the plan and had the hub check names, versions and rules.publication publishstaged everything invisibly and committed it in one step, so the release appeared whole.status,resumeandabortlook after a transaction that was interrupted; publishing the same plan again is always safe.
You can stop here
If you publish releases of several packages, or publish from CI, you have the complete publishing toolkit.
Next
- Logging in and Logins and profiles cover the account behind every publication.
- Optional: Releasing a workspace for choosing which members to release together.