Publish a template
Choose a repo layout for a yoink add template, tell consumers which ref to pin, and submit a template to the bundled set.
Any GitHub repo can hold a template. To write the template first, see Write a template for yoink add.
Choose a repo layout
A consumer ref has the form gh:owner/repo[@ref]/path. The path is the directory in the repo that holds template.yaml. The path cannot be empty, so put the template in a subdirectory.
| Layout | Consumer ref | Use it when |
|---|---|---|
| One repo for each template | gh:yourname/yoink-template-clickhouse/clickhouse |
You want a template that is easy to advertise, to vendor, and to fork. |
| A templates monorepo, with one subdirectory for each template | gh:yourname/yoink-templates/clickhouse |
You maintain several templates and want less overhead. |
| A directory in your existing project | gh:yourname/your-app/templates/your-app |
The template is specific to your project and lives next to the code that it deploys. |
yoink downloads the full repo tarball. It caps the download at 50 MB and the unpacked size at 200 MB. If your repo is larger, move the template to its own repo.
Tell consumers which ref to pin
- In your README, write the ref that you recommend:
mainfor the latest changes, or a tag for stability. - If the template needs a yoink feature from a later version, set
yoink_min_version: "X.Y.Z"in the manifest.
With yoink_min_version: set, an older yoink stops and tells the consumer to upgrade yoink or to pin an older template. Without it, an older yoink can render a wrong config with no error.
For how branch, tag, and SHA refs resolve, see Template refs.
Submit a template to the bundled set
The six bundled templates (postgres, redis, meilisearch, rustfs, restic-backups, openclaw) are in the yoink repo at /templates/<name>/. A bare name, for example yoink add postgres, resolves to templates/postgres in oddur/yoink. PRs that add a bundled template are welcome. For the bar that a new template must pass, see The bundled set.
A PR must meet these four acceptance criteria:
- The template renders valid YAML. The
tests/add_integration.rstest walkstemplates/*/template.yaml. Make sure that the test passes with your template. - The template passes a smoke test on a real host. On a real Docker host, run
yoink init, thenyoink add <yourname>, thenyoink up. Then use the service end-to-end. Put the output in the PR. - The hardening overrides are documented. If you needed
user: "0:0",cap_add: [...], orread_only: false, explain why in a comment inservice.yaml.tmpl. Name the entrypoint operation and the file. - The secret names agree. This criterion applies if your template seals a secret. Each
env_from_secrets:reference in the rendered fragment must use a name thatsecrets[].name:produces. The integration test finds mismatches.
These criteria are not required for a third-party template in your own repo.
See also
- Write a template for
yoink add: the example template and the development loop. - Template manifest: the manifest fields, the ref rules, and the download limits.
- Templates (
yoink add): how versions resolve and what the bundled set is for. - Adding a service via
yoink add: how consumers add your template.