Journeys
Each guide opens with a problem you might have and walks you to a working plugin end-to-end. Read in any order — they're independent. Most teams need two or three of these, not all four.
| You have… | Read | What you build |
|---|---|---|
| Your own CI/CD templates and don't want forge's defaults | your-own-ci | A git-distributed bundle that emits your CI files from contract data. Per-system templates: GitLab · GitHub Actions · Jenkins · CircleCI |
| A strict project layout (directory structure, lint config, Dockerfile, README template) | your-own-scaffolding | A bundle that emits the full project skeleton — pyproject.toml, src/<id>/, tests, Dockerfile, pre-commit config |
| Governance rules — every product must declare a steward, classifications must come from a vocabulary, etc. | custom-validator | A Validator plugin auto-discovered at fluid validate, distributed via pip install |
| An invariant that only matters at deploy time (env vars present, image signed, bundle digest matches) | apply-hook | An apply hook that runs inside fluid apply, with a documented override flag |
How journeys differ from examples
The examples are reference: "here's a complete working plugin, every line shown." The journeys are how-tos framed by the problem: "here's the situation you're in, here's why this pattern fits, here's how to ship it."
If you're new to plugin authoring, read the quickstart first — it's the shortest path to a runnable plugin and gives you the mental model the journeys assume.
What every journey has in common
The journey guides share a shape, so you can scan them the same way:
- The problem in one paragraph — what you have, what you want, why this pattern is the right fit.
- The mental model in one diagram — boxes and arrows for the data flow.
- A "see the result first" section — what success looks like before you build anything.
- Step-by-step build — every step has a "you'll see X when you run Y" check.
- Cloud / CI variations split out — sub-pages per provider (e.g. GitLab / GitHub Actions / Jenkins / CircleCI for the CI journey) so the hub page stays scannable for the 80% who only care about one of them.
- "You'll know it worked when…" — concrete acceptance criteria.
- "When NOT to use this pattern" — honest about the limits.
- "Common gotchas" — failure modes, with the fix inlined.
Source code
The plugins built in these journeys are mirrored from the SDK's examples/ directory where possible, and the scaffold engine's reference bundle:
- SDK examples:
Agenticstiger/forge-cli-sdk/examples/ - Custom-scaffold reference bundle:
Agenticstiger/data-product-forge-custom-scaffold/tests/fixtures/reference_bundle/
The CI, scaffolding, validator and apply-hook walkthroughs were run on CLI 0.18.1 with SDK 0.10.0 and data-product-forge-custom-scaffold 0.4.1. The bundle examples bind the bundle with kind: path, because the engine refuses file:// git URLs, so the git clone path was not run. The "Variations" snippets in the apply-hook pages, other than the scaffold-lock check, were not run.