Registry guide

The Picoo Registry distributes operations and workflows. Users see package IDs, versions, publisher trust, contracts, and permissions. The service behind the Registry is not part of workflow execution.

Run an operation from the Registry

The shortest path is usually run:

picoo run picoo/github/create-issue \
  --input repo=picoo-dev/picoo \
  --input title="Fix login"

Picoo uses the installed copy when it is available. Otherwise it can fetch the operation from the configured Registry and then run it.

Pin a version when repeatability matters:

picoo run picoo/github/create-issue \
  --version 1.2.0 \
  --input repo=picoo-dev/picoo \
  --input title="Fix login"

Use --offline to prevent all Registry access.

Install before running

Install explicitly when you want to review or prepare an operation first:

picoo registry install picoo/github/create-issue \
  --from https://registry.example/picoo-ops.git \
  --version 1.2.0

--from accepts a Registry directory or Git URL. Add --git-ref when the Registry should be read from a particular branch, tag, or commit.

After installation:

picoo show picoo/github/create-issue
picoo run picoo/github/create-issue --offline --version 1.2.0 --input repo=picoo-dev/picoo --input title="Fix login"

Publish an operation

Test the operation and inspect its contract first:

picoo show alice/demo/greet
picoo run alice/demo/greet --input name=Nahid

Publish its current version to a Registry checkout:

picoo registry publish alice/demo/greet --to ../picoo-registry

Published versions are immutable. To release a change, choose a new semantic version, test it, and publish again:

picoo update alice/demo/greet --version 0.2.0
picoo run alice/demo/greet --input name=Nahid
picoo registry publish alice/demo/greet --to ../picoo-registry

Use semantic versions in the form major.minor.patch:

Increase patch for a compatible fix.
Increase minor for a compatible new capability.
Increase major for a breaking contract change.

Do not reuse a published version number.

Publish to your configured Registry

When your Registry account allows publishing, ask its operator for a token limited to write:package, then store it once with your protected Git credential helper:

picoo auth login --owner alice

The registry owner defaults to the package ID namespace, so publishing is then one command:

picoo registry push alice/demo/greet
picoo workflow push workflows/article.toml \
  --id alice/workflows/article \
  --version 0.1.0

For CI, set the Registry URL and token as masked environment secrets. Keep the token out of shell history and source control.

export PICOO_REGISTRY_URL="https://registry.example"
export PICOO_FORGEJO_TOKEN="your-token"

picoo registry push alice/demo/greet \
  --owner alice \
  --token-env PICOO_FORGEJO_TOKEN

$env:PICOO_REGISTRY_URL = "https://registry.example"
$env:PICOO_FORGEJO_TOKEN = "your-token"

picoo registry push alice/demo/greet `
  --owner alice `
  --token-env PICOO_FORGEJO_TOKEN

--token-env is the name of the environment variable, not the token itself. The package ID namespace must match --owner; only Picoo’s release automation may publish under the reserved picoo/* namespace. You can also pass the Registry URL directly with --to.

Publish a workflow with an exact dependency lock:

export PICOO_REGISTRY_OWNER=alice
export PICOO_FORGEJO_TOKEN=your-token
picoo workflow push workflows/article.toml \
  --id alice/workflows/article \
  --version 0.1.0

Picoo validates the workflow and its policy before upload. The package includes the workflow definition and exact versions of all referenced operations, but does not duplicate those operation bundles.

Published workflow versions are immutable. Release a changed workflow under a new semantic version. A workflow ID must use the publisher’s Forgejo namespace; for example, owner alice publishes alice/workflows/article.

Run a public workflow directly by ID. Picoo downloads the immutable workflow and any missing dependencies pinned by its lock before execution:

picoo workflow run alice/workflows/article \
  --version 0.1.0 \
  --input topic="Small agent tools"

Install it without running when you want to inspect or prepare it first:

picoo workflow pull alice/workflows/article --version 0.1.0
picoo workflow run alice/workflows/article --offline --version 0.1.0 \
  --input topic="Small agent tools"

--offline fails closed if the workflow or an exact dependency is unavailable. Picoo never silently substitutes a different installed dependency version.

Install an exact version from a configured hosted Registry with pull:

picoo registry pull alice/demo/greet \
  --version 0.2.0 \
  --from https://registry.example \
  --token-env PICOO_FORGEJO_TOKEN

Readers of public packages may not need a token. Follow the access instructions provided by your Registry operator.

Build a trusted Hub catalog

Hub operators explicitly approve every Forgejo owner included in the public catalog. Trust labels come from operator configuration, not from package metadata supplied by publishers:

picoo registry catalog \
  --from http://forgejo:3000 \
  --owner picoo,alice,bob \
  --official-owner picoo \
  --verified-owner alice \
  --exclude-id picoo/demo/hello \
  --out site/public/catalog.json

Run catalog generation inside the private deployment network. The public Hub proxy intentionally exposes package downloads only; it does not expose Forgejo’s package-list or administration APIs.

Official is reserved for owners controlled by the Picoo project.
Verified means the registry operator verified that publisher account.
Community is an explicitly approved owner without either designation.

An excluded package remains in storage but is not advertised by the Hub. Use the Registry API with publisher credentials for permanent deletion so package records and object storage are cleaned up together.

Sign a release

A signature lets users verify that a package was signed by a key they trust. Create a signing key once:

picoo registry keygen alice

Keep the private key private. Share the public key through a trusted channel. Sign when publishing:

picoo registry publish alice/demo/greet \
  --to ../picoo-registry \
  --sign-with alice

The same --sign-with alice option works with registry push.

Trust a publisher

Import the public key you received:

picoo registry trust alice --public-key alice.pub

Then require that key and reject unsigned packages:

picoo registry install alice/demo/greet \
  --from ../picoo-registry \
  --version 0.2.0 \
  --trust-key alice \
  --require-signature

You can repeat --trust-key when more than one publisher key is acceptable. The same trust options work with registry pull.

Package hashes detect changed files. A required signature also checks that the package was signed by one of the keys you selected. A signature does not prove that the operation is safe, so inspect its contract and permissions before you run it.

Common Registry problems

The version already exists. Published versions cannot be overwritten. Bump the operation version, test it, and publish the new version.

Authentication failed. Run picoo auth status --owner OWNER. For CI, confirm that the token environment variable exists and that --token-env contains its name. Do not paste the token itself into the command.

A signature is missing or untrusted. Get the publisher’s public key through a trusted channel, import it with registry trust, and retry. Do not remove --require-signature just to make an unknown package install.

A package changed during verification. Stop using that package version and contact the Registry operator or publisher. A published package should not change after release.

You need a network-free run. Install the exact version first, then run with both --offline and --version.