Forge Overview
Forge is Shoehorn’s self-service workflow engine: a form-based UI for scaffolding services, creating repositories, provisioning infrastructure, and orchestrating multi-step automations, with optional approval gates.
Concepts
Section titled “Concepts”A mold is a reusable YAML template that defines inputs, steps, and actions. Molds live in your repository under .shoehorn/molds/ and are discovered automatically by the crawler. Once indexed, they appear in the Forge section of the portal.
A run is a single execution of a mold. Runs track status in real time:
| Status | Description |
|---|---|
pending | Queued for execution |
pending_approval | Waiting for approval before execution |
executing | Currently running steps |
completed | All steps finished successfully |
failed | A step encountered an error |
cancelled | Cancelled by the user |
Approval workflows
Section titled “Approval workflows”Molds can require approval before execution. You define who needs to approve and how many approvals are needed. Runs enter pending_approval status until all approval steps are satisfied.
Using Forge
Section titled “Using Forge”- Open Forge in the sidebar
- Browse or search for a mold
- Click the mold card to view its details and input form
- Fill in the required fields — the form validates as you type
- Click the primary action button to create a run
- Monitor progress in the Events tab on the run detail page
Use Dry Run to validate inputs without executing the steps.
Use an Idempotency Key to prevent duplicate runs when retrying.
Two step formats
Section titled “Two step formats”Molds support two step formats; the engine picks one based on the field you use.
Scaffolder steps use action: and target GitHub or the catalog (create repos, files, topics, PRs, register entities). The repo-create, file-create, template-apply, topics-set, PR-create, and catalog-register actions are idempotent: re-running a failed run is safe. The repo-delete action is destructive and not idempotent.
Workflow steps use adapter: and handle multi-system orchestration (HTTP calls, catalog lookups, logging). They support explicit dependencies and conditional execution.
Creating molds
Section titled “Creating molds”See:
- Creating Molds — mold structure, scaffolder actions, workflow adapters, input schemas, conditional fields, approval flows, and worked examples
- Approval Workflows — configuring multi-step approval chains
Permissions
Section titled “Permissions”| Role | Can do |
|---|---|
| Any authenticated user | Browse molds, run workflows, cancel/retry own runs |
| Approver (listed in approval flow) | Approve or reject pending approval requests |
| Admin | Manage all molds, cancel/retry any run |