From 9dda626a067699a09f471ee7efce43ca7e63e761 Mon Sep 17 00:00:00 2001 From: Istvan Docsa Date: Sun, 25 Oct 2026 08:24:15 +0000 Subject: [PATCH 1/3] docs: add Action setup and distinguish submission exit from verdict (ENG-1349) --- README.md | 10 ++-- .../how-to/add-the-github-action.agent.md | 11 +++++ docs/product/how-to/add-the-github-action.md | 47 +++++++++++++++++++ docs/product/nav.yaml | 1 + 4 files changed, 64 insertions(+), 5 deletions(-) create mode 100644 docs/product/how-to/add-the-github-action.agent.md create mode 100644 docs/product/how-to/add-the-github-action.md create mode 100644 docs/product/nav.yaml diff --git a/README.md b/README.md index 89d97d6..3a3c3ac 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -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 }} @@ -335,3 +333,5 @@ Linro install and a valid token. See [NOTICE](NOTICE). Issues and feature requests: . 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). diff --git a/docs/product/how-to/add-the-github-action.agent.md b/docs/product/how-to/add-the-github-action.agent.md new file mode 100644 index 0000000..af2bf13 --- /dev/null +++ b/docs/product/how-to/add-the-github-action.agent.md @@ -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 separate check for github-ci and 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 fallback project/org with contradiction refusal, 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. diff --git a/docs/product/how-to/add-the-github-action.md b/docs/product/how-to/add-the-github-action.md new file mode 100644 index 0000000..f973067 --- /dev/null +++ b/docs/product/how-to/add-the-github-action.md @@ -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 that check in branch protection if it is your merge gate. 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. diff --git a/docs/product/nav.yaml b/docs/product/nav.yaml new file mode 100644 index 0000000..f0096df --- /dev/null +++ b/docs/product/nav.yaml @@ -0,0 +1 @@ +- page: how-to/add-the-github-action From 3f392593892d9e17cc5c3977f344fd21bdaadb7e Mon Sep 17 00:00:00 2001 From: Istvan Docsa Date: Sun, 25 Oct 2026 08:45:56 +0000 Subject: [PATCH 2/3] docs: qualify GCP project-input precedence --- docs/product/how-to/add-the-github-action.agent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/product/how-to/add-the-github-action.agent.md b/docs/product/how-to/add-the-github-action.agent.md index af2bf13..ceb5331 100644 --- a/docs/product/how-to/add-the-github-action.agent.md +++ b/docs/product/how-to/add-the-github-action.agent.md @@ -6,6 +6,6 @@ Inputs plan/preview are newline-separated repeatable paths, combine into one pay 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 separate check for github-ci and 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 fallback project/org with contradiction refusal, 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. +--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. From 97549ad06dab06d16002718140506e4197528ad1 Mon Sep 17 00:00:00 2001 From: Istvan Docsa Date: Sun, 25 Oct 2026 08:48:58 +0000 Subject: [PATCH 3/3] docs: require submission job and policy check as separate gates --- docs/product/how-to/add-the-github-action.agent.md | 2 +- docs/product/how-to/add-the-github-action.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/product/how-to/add-the-github-action.agent.md b/docs/product/how-to/add-the-github-action.agent.md index ceb5331..9f656e1 100644 --- a/docs/product/how-to/add-the-github-action.agent.md +++ b/docs/product/how-to/add-the-github-action.agent.md @@ -4,7 +4,7 @@ Preconditions reviewed pinned Action ref and compatible published CLI version, e 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 separate check for github-ci and inspect Result/coverage; build an explicit result-aware policy gate if using cli mode. +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. diff --git a/docs/product/how-to/add-the-github-action.md b/docs/product/how-to/add-the-github-action.md index f973067..5ed81ab 100644 --- a/docs/product/how-to/add-the-github-action.md +++ b/docs/product/how-to/add-the-github-action.md @@ -40,7 +40,7 @@ jobs: 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 that check in branch protection if it is your merge gate. A green submitting step does not mean a passing simulation. +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.