Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,7 @@ Run your Terraform plans and Pulumi previews through Linro's real policy engine
Any number of sources, in any mix, become **one** simulation with one verdict.

Not a linter. The simulation goes through the same plugin normalization and the
same checks Linro runs against your live inventory, so a passing simulation
means a passing apply.
same checks Linro runs against your live inventory, so the result reflects supported checks over the proposed inventory. It does not guarantee a passing apply or complete provider/check coverage.

```yaml
name: Linro
Expand Down Expand Up @@ -60,8 +59,7 @@ and the result appears moments later as a separate check run named after your
That surprises people, so it is worth being explicit: **a red simulation does
not fail this step.** Require the check run in your branch protection rules —
that is the gate. If you would rather block the job itself, set
`integration: cli`, which polls for the result and exits non-zero on failure,
at the cost of the check-run UI.
`integration: cli`, which polls and prints the result without the check-run UI. A completed run can still exit zero with violations, so an explicit result-aware gate is required.

## Inputs

Expand Down Expand Up @@ -223,7 +221,7 @@ checking anything more.
## Pulumi

```yaml
- run: pulumi preview --json > preview.json
- run: pulumi preview --show-sames --json > preview.json
working-directory: infra
env:
PULUMI_CONFIG_PASSPHRASE: ${{ secrets.PULUMI_PASSPHRASE }}
Expand Down Expand Up @@ -335,3 +333,5 @@ Linro install and a valid token. See [NOTICE](NOTICE).
Issues and feature requests: <https://github.com/linro-io/simulation-github-action/issues>.
If you find yourself leaning on `extra-args`, that is worth an issue — a
first-class input is better than a string.

Operator guide: [Add the GitHub Action](docs/product/how-to/add-the-github-action.md).
11 changes: 11 additions & 0 deletions docs/product/how-to/add-the-github-action.agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Add the GitHub Action

Preconditions reviewed pinned Action ref and compatible published CLI version, existing workflow-produced plan/preview, active SIMULATIONS/API PAT in secret, correct server/scope and configured real GitHub check path. {{page:service/concepts/simulations}} provides result interpretation.

Inputs plan/preview are newline-separated repeatable paths, combine into one payload/verdict. opentofu labels plans; native selects native preview dialect. version is CLI independently of Action ref, current old defaultv0.2.1 must not be assumed capable of new bindings. Current binary floor/installed plugin compatibility must be checked. Linux/macOS AMD64/ARM64 supported; no Windows build. marketplace-url controls artifact source, pin reviewed availability.

Default integration github-ci, strictfalse, labellinro-simulate. PR job contents:read,id-token:write when gateway audience discovery requires minting. CLI asks GetSimulatorMeta for actual audience; empty means direct App path, nonempty minted OIDC. Never copy staging audience to prod or override casually. Throwaway local credentials only support cli-mode smoke, not real PR checks. Explicit integration cli polls but CLI COMPLETED can still return0 with violations: neither mode's step exit proves compliant. Require BOTH submitting Actions job and separate configured simulation check: strict local-skip failure occurs after supported subset upload, so green subset check can coexist with failed job. Inspect Result/coverage; build an explicit result-aware policy gate if using cli mode.

--strict only local skips, not all server evaluated checks/resources. --dry-run no submission/verdict. Actual AWS account/region, GCP explicit resource project wins over project input; fallback provider-project contradictions are refused, and organization uses its source-aware fallback, OTC exact connector domain; no mock scope for gate. Pulumi preview --show-sames --json required for unchanged sibling context. Duplicate paths refused but different files can duplicate real infrastructure. Unique label avoids concurrent check races.

Template intentionally uses REVIEWED refs/version and assumes plan.json already exists; do not advertise as a fully executable end-to-end workflow. Token from secret only, no debug trace of secrets. Review plan artifact retention. Default client poll5m does not cancel server on timeout. Provider/API and check coverage limits remain; passing simulation cannot guarantee passing apply.
47 changes: 47 additions & 0 deletions docs/product/how-to/add-the-github-action.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
id: how-to/add-the-github-action
title: Add the GitHub Action
kind: how-to
audience: customer
reader: both
covers: []
verified: 2026.10.5
---

# Add the GitHub Action

Run a reviewed Terraform plan or Pulumi preview through Linro from a pull request. Read {{page:service/concepts/simulations}} for scope and coverage limits. The simulation check is separate from the Action step that submits the work.

## Prepare the workflow

Have the repository owner choose a reviewed Action revision and compatible published simulator version. Configure the Linro server variable and a simulation-scoped token in repository secrets. Do not paste a token into the workflow.

```yaml
name: Linro simulation
on: pull_request
permissions:
contents: read
id-token: write
jobs:
simulate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# Produce and review plan.json with your normal Terraform workflow first.
- uses: linro-io/simulation-github-action@REVIEWED_ACTION_REF
with:
version: REVIEWED_COMPATIBLE_CLI_VERSION
plan: plan.json
server: ${{ vars.LINRO_SERVER }}
token: ${{ secrets.LINRO_TOKEN }}
account: "AWS_ACCOUNT_ID"
region: AWS_REGION
strict: "true"
label: linro-reviewed-plan
```

When it worked, the submission step is accepted and a separate simulation check appears with the configured label. Review its actual findings and coverage, and require both the submitting simulate job and that simulation check in branch protection if they are your merge gate. Strict mode can upload the supported subset before the job fails for local skips; the subset check alone can still be green. A green submitting step does not mean a passing simulation.

Known gaps: this fragment assumes your preceding workflow produces plan.json and has its normal cloud permissions. It does not provide a complete Terraform pipeline. Pull-request OIDC permission is required for a gateway-backed check; a direct GitHub App deployment differs. Ask your installation operator which path is configured. A throwaway local App key cannot create real PR checks.

For Pulumi, generate the preview with unchanged resources included, then set preview to its file. For several plans or previews, put one path per line and use a distinct label for concurrent simulations. Do not use overlapping source files or mock scope values for a deployment gate.
1 change: 1 addition & 0 deletions docs/product/nav.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- page: how-to/add-the-github-action
Loading