Get started¶
Build confidence before granting write access. This journey begins with an
exact package version and a narrow read-only plan, then introduces apply only
after the desired and observed states are clear.
Safe starting point: the first four stages do not change GitHub. The final stage mutates only the repository and setting you explicitly review.
Journey¶
01 · Runtime
Install Octoform¶
Pin the documented package, choose how to invoke it, and verify the executable.
02 · Identity
Authenticate safely¶
Select a credential for interactive or automated use and expose it only to the current process.
03 · Intent
Write one policy¶
Declare a single managed value and leave every omitted repository setting untouched.
04 · Evidence
Produce a plan¶
Read GitHub state, narrow the repository selection, and interpret changes, warnings, and capability blocks.
05 · Change
Apply and verify¶
Approve the exact plan, confirm the result, and plan again to prove the desired state is converged.
06 · Model
Understand the model¶
Learn why omitted values are unmanaged, how precedence is resolved, and why an uncertain operation is blocked instead of guessed.
What you need¶
| Requirement | Minimum | Purpose |
|---|---|---|
| Node.js | 20 |
Run the ESM command-line package |
| GitHub owner | Personal account or organization | Identify the repository owner to inspect |
| GitHub credential | Read access to the selected repositories | Obtain observed state and capability evidence |
| Local YAML file | One explicit policy | Declare only the state Octoform may manage |
Use a disposable or low-risk repository for the first apply. A representative repository is useful; a production-critical repository is not required to learn the workflow.
Where to go afterwards¶
- Use validated examples as starting points for broader policies.
- Follow the full plan and apply operating procedure before routine use.
- Move recurring checks into CI/CD automation.
- Consult the configuration reference for exact fields, precedence, and applicability.