managed

Appearance

Publishing packages ​

Don't want to run a bucket? Hosted repositories do all of this for you on managed.works, no S3, no signing key to manage. This page is for self-hosting your own registry.

Publishing pushes a package to an S3-compatible bucket (AWS S3, Cloudflare R2, DigitalOcean Spaces, MinIO…) laid out so consumers can pull it over plain HTTP. Most people only ever consume repositories, you only need this if you run your own.

1. One-time: a signing key ​

A repository's index is signed so consumers can trust what they pull. Generate a keypair once:

bash
managed repository keygen
  • Keep the private key secret (it goes in your publish config, below).
  • Give consumers the public key, they put it in public_key: on their repo entry. (For the official repo, the public key is built into the binary.)

2. Publish credentials (kept out of version control) ​

Publishing config does not live in managed.yaml (that's consumer config). Put it in a gitignored .managed-publish.json at your package repo root:

json
{
  "name": "my-repo",
  "endpoint": "<account>.r2.cloudflarestorage.com",
  "region": "auto",
  "bucket": "my-packages",
  "access_key": "…",
  "secret_key": "…",
  "signing_key": "<base64 ed25519 private key from keygen>"
}

.managed-publish.json is already in managed's .gitignore. Every field can be overridden with an environment variable (handy for CI secrets):

MANAGED_PUBLISH_NAME, MANAGED_PUBLISH_ENDPOINT, MANAGED_PUBLISH_REGION,
MANAGED_PUBLISH_BUCKET, MANAGED_PUBLISH_ACCESS_KEY, MANAGED_PUBLISH_SECRET_KEY,
MANAGED_PUBLISH_SIGNING_KEY

The bucket should be public-read if you want credential-free HTTP pulls (recommended); otherwise consumers need read credentials too.

3. Push a package ​

bash
managed repository push ./my-service     # defaults to the current directory

This validates the package, uploads packages/<name>/<version>/<name>-<version>.tar.gz (plus a manifest), and updates and signs the index. Bump version: in service.yaml for each release, published versions are immutable (--force overrides).

Bucket layout ​

index.json                                   # signed manifest: every package + version + sha256
index.json.sig                               # Ed25519 signature of index.json
packages/<pkg>/<version>/<pkg>-<version>.tar.gz
packages/<pkg>/<version>/manifest.json

Consumers fetch index.json (verifying the signature), then download the latest tarball of each package and verify its sha256 against the index.

Recovering the index ​

If the index is ever lost or out of date (or several machines pushed at once), rebuild it from the bucket's contents:

bash
managed repository reindex

How consumers use it ​

yaml
# their managed.yaml
repos:
  - url: https://my-packages.example.com   # the bucket's public URL
    type: registry
    public_key: "<your public key>"
bash
managed repository pull