A zero-config GitHub Action for OpenTofu/Terraform: plan on every pull request, apply on merge, state stored in Cloudflare R2 or AWS S3. No HCP Terraform, no Atlantis server, no Kubernetes cluster. State never touches the local repo checkout.
State stored inside a repo checkout is a real risk the moment that repo is
public, or even just widely cloned: secrets in plan output, resource IDs, tfvars
values, all sitting in git history. iac-cicd keeps state in an S3-compatible
bucket, either Cloudflare R2 (free tier: 10 GB storage, 1M write + 10M read
ops/month, no egress fees) or plain AWS S3, and drives plan/apply from
GitHub-hosted runners. R2 needs only a Cloudflare account beside GitHub; S3
needs only an AWS account.
-
Create a bucket.
- R2: Cloudflare dashboard → R2, or
wrangler r2 bucket create <name>. - S3: AWS Console → S3, or
aws s3 mb s3://<name> --region <region>.
- R2: Cloudflare dashboard → R2, or
-
Create scoped credentials for that bucket only.
- R2: Cloudflare dashboard → R2 → Manage API Tokens → Create API Token → Object Read & Write, scoped to the one bucket.
- S3: an IAM user or role with a policy limited to that one bucket
(
s3:GetObject,s3:PutObject,s3:DeleteObject,s3:ListBucket).
-
Add repo secrets (Settings → Secrets and variables → Actions):
- R2:
R2_ACCOUNT_ID,R2_ACCESS_KEY_ID,R2_SECRET_ACCESS_KEY,R2_BUCKET. - S3:
AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY,AWS_BUCKET, plus the bucket's region.
- R2:
-
Add one empty backend block to your OpenTofu/Terraform config, this is the only line this tool asks you to commit:
terraform { backend "s3" {} }
Partial backend configuration is a language requirement in both OpenTofu and Terraform: the block must exist, but everything inside it (bucket, key, region, credentials) is supplied at
inittime.iac-cicdsupplies all of it, so this block stays empty forever. Yes, the block is literally named"s3"even for R2, R2 is consumed through its S3-compatible API. -
Copy the example workflow. See
examples/plan-apply.ymlfor a complete plan-on-PR / apply-on-merge pipeline, or the minimal form below.Cloudflare R2 (
backenddefaults tor2):name: iac on: pull_request: push: branches: [main] permissions: contents: read pull-requests: write jobs: iac: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - uses: zeroconfigio/github-action-iac-cicd@v1 with: account-id: ${{ secrets.R2_ACCOUNT_ID }} access-key-id: ${{ secrets.R2_ACCESS_KEY_ID }} secret-access-key: ${{ secrets.R2_SECRET_ACCESS_KEY }} bucket: ${{ secrets.R2_BUCKET }}
AWS S3, same workflow, three lines different:
- uses: zeroconfigio/github-action-iac-cicd@v1 with: backend: s3 region: us-east-1 access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} bucket: ${{ secrets.AWS_BUCKET }}
That's it. On a pull request, this posts (and keeps updating, no comment
spam) a sticky comment with the plan. On merge to the default branch, it
applies. Both directions read/write the same state key, derived by default
from <owner>/<repo>[/<working-directory>]/terraform.tfstate, so multiple
root modules in one repo (pass different working-directory values) don't
collide.
The credentials above only authenticate the state backend. Whatever
you're actually provisioning (AWS, Cloudflare, GitHub, ...) needs its own
provider credentials, wired into the same job through your own secrets and
provider {} blocks. iac-cicd never sees or needs those.
Set backend: s3 and pass endpoint explicitly (Backblaze B2, MinIO, and
similar). This is the escape hatch, not a supported target: iac-cicd only
tunes its defaults (use_path_style, checksum/validation skips, encrypt)
for R2 and real AWS S3, a third provider may need extra-args or may not
work at all depending on how closely it follows the S3 API.
iac-cicd runs inside whatever job calls it, so approval gates are a
property of that job, not something the action can enforce internally. Put
the apply job behind a GitHub Environment
with a required reviewer, see examples/plan-apply.yml for the full pattern.
command auto-detect treats plan as the safe default for any event that
isn't push, not just pull_request. The shipped examples/plan-apply.yml
is unaffected by this: its plan job already gates on
github.event_name == 'pull_request' and its apply job gates on
github.event_name == 'push', so neither job ever hits the action with any
other event type. This only matters for consumers that call the action
directly from other event types (a scheduled drift check, for example, see
Drift detection).
policy-command is an optional hook. It's not a bundled policy engine,
iac-cicd doesn't ship or install one. Point it at whatever policy tool
you already use (OPA/conftest, Sentinel, a custom script) and the action
runs it for you.
The command receives the run's terraform show -json-rendered plan via the
IAC_PLAN_JSON env var, a path to the plan file on disk. A nonzero exit
fails the check, which fails the job.
It runs twice: once at plan-time, once at apply-time. That's deliberate,
not redundant. Plan and apply are separate CI runs on separate trigger
events, a PR's plan and the later merge's apply are different
invocations. So this doesn't guarantee the plan a reviewer saw on the PR is
exactly what gets applied at merge time. What it does guarantee: the hook
always sees, and can block, exactly what's about to happen, immediately
before it happens, in both places where "about to happen" occurs. That's
defense-in-depth against a bypassed branch-protection check, like an admin
force-merge or a required-check list someone set up wrong, not extra
safety for its own sake.
policy-command: "conftest test --policy ./policy $IAC_PLAN_JSON"conftest/OPA above is just an example. iac-cicd doesn't install or
require it, or any other policy tool. Your own workflow needs to install
whatever policy-command points at before this action's step runs.
policy-command runs as raw shell text, the same trust level extra-args
already has elsewhere in this action. Keep it static workflow config.
Never build it from PR-controlled input like a title, label, or comment,
there's no quoting or sanitization boundary here.
For backend: s3, you can skip long-lived AWS keys and assume an IAM role
through GitHub's OIDC token instead. Set aws-role-arn (and optionally
aws-role-session-name) and iac-cicd assumes that role via
aws-actions/configure-aws-credentials before running init. This only
applies to backend: s3, R2 has no OIDC equivalent, it authenticates
through its own API token.
aws-role-arn is additive to access-key-id/secret-access-key as
inputs, not a replacement for them: its presence is what selects OIDC auth
over static keys. If you set both aws-role-arn and the static keys, the
action fails loud with a validation error instead of silently picking one.
That's by design.
The calling job needs permissions: id-token: write. iac-cicd can't
grant that permission on your behalf, GitHub permissions are set at the
workflow or job level only, an action included in a job has no way to add
scopes to it. If that permission is missing,
aws-actions/configure-aws-credentials fails at runtime with AWS's own
AssumeRoleWithWebIdentity error, not a message from this action.
You also need the GitHub OIDC provider already registered in your AWS account. That's a one-time AWS account setup step this action doesn't perform for you, see GitHub's docs on configuring OpenID Connect in AWS for how to set it up.
A trust policy scoped to the consumer repo looks like this:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
},
"StringLike": {
"token.actions.githubusercontent.com:sub": "repo:<owner>/<repo>:*"
}
}
}
]
}Minimal with: block for OIDC:
permissions:
id-token: write
steps:
- uses: zeroconfigio/github-action-iac-cicd@v1
with:
backend: s3
region: us-east-1
aws-role-arn: arn:aws:iam::123456789012:role/iac-cicd-deploy
bucket: ${{ secrets.AWS_BUCKET }}No access-key-id/secret-access-key needed, the role is assumed
directly.
iac-cicd has no dedicated "drift" mode, drift detection is just the same
plan/apply primitives run on a schedule. See
examples/drift-detection.yml for a
complete on: schedule (plus workflow_dispatch for manual runs) workflow
that calls the action with no command: override. Because the triggering
event isn't push, the auto-detect default resolves to plan (see
Manual approval before apply), so a
scheduled run never applies anything on its own, it only reports what's
changed outside the pipeline.
When the action's has-changes output is 'true', the example's follow-up
step opens or updates a single GitHub Issue instead of filing a new one on
every run. It tags the Issue with a drift-detection label and searches
only issues carrying that label for its marker before deciding whether to
PATCH an existing Issue or POST a new one, so the search stays bounded
instead of scanning every open issue in the repo.
.github/dependabot.yml watches every pinned github-actions SHA, in
action.yml and in the workflow files, on a weekly schedule, and opens a
PR when a pin goes stale.
See SECURITY.md for how to verify a pin yourself and
where to report a vulnerability, this README doesn't repeat that here.
On a v* tag push, .github/workflows/release.yml archives the tagged
tree and attests it with actions/attest-build-provenance. The
attestation proves one specific thing: a tarball of the tagged tree was
produced by that workflow, in this repo, for that tag. It's not a full
build-provenance chain for a compiled artifact, this project doesn't
produce one, there's no compiled binary or container image for a chain
like that to cover. A real guarantee, a narrower one than the phrase
"build provenance" might suggest by itself.
Manual follow-up, not something any workflow configures: once v1
is tagged, enable tag protection on v* in the repo's Settings
(Rulesets, or branch/tag protection). Without it, the tag could be
silently repointed at different code later, and nothing in this repo's
workflows would catch that.
| Input | Required | Default | Description |
|---|---|---|---|
tool |
no | opentofu |
opentofu or terraform |
tool-version |
no | latest |
Version to install |
working-directory |
no | . |
Root module directory |
command |
no | auto | Override auto-detect (apply on push, plan otherwise) |
backend |
no | r2 |
r2 (Cloudflare R2) or s3 (AWS S3) |
bucket |
yes | Bucket for state | |
access-key-id |
required unless aws-role-arn is set (s3), or always (r2) |
S3-compatible access key ID | |
secret-access-key |
required unless aws-role-arn is set (s3), or always (r2) |
S3-compatible secret access key | |
aws-role-arn |
no | IAM role ARN to assume via OIDC, s3 only, see OIDC for AWS S3 |
|
aws-role-session-name |
no | iac-cicd |
Session name used when assuming aws-role-arn |
account-id |
required for r2 |
Cloudflare account ID (ignored for s3, or when endpoint is set) |
|
region |
required for s3 |
auto for r2 |
Bucket region |
endpoint |
no | derived | Override the S3-compatible endpoint URL |
state-key |
no | derived | Object key for the state file |
extra-args |
no | `` | Extra flags appended to the plan that produces the applied plan file (not to the final apply <planfile> call, which can't take flags like -var-file once a plan is saved) |
comment-on-pr |
no | true |
Post/update a sticky PR comment on plan |
policy-command |
no | `` | Command checked against the JSON plan at plan-time and apply-time; nonzero exit fails the run, see Policy gate |
github-token |
no | job token | Token used to post the PR comment |
| Output | Description |
|---|---|
exitcode |
Exit code of the plan/apply command (0 = no changes, 2 = plan has changes) |
has-changes |
'true' if the plan detected changes |
State locking uses each backend's native S3 conditional-write lock
(use_lockfile = true), not DynamoDB. This requires OpenTofu ≥ 1.10 or
Terraform ≥ 1.11; both are the default latest resolves to today. If you
pin tool-version below those, locking silently fails to protect concurrent
runs, set your project's required_version accordingly so mismatches fail
loud instead of quiet.
Both R2 and S3 encrypt objects at rest by default (S3 has since 2023,
unconditionally). For backend: s3, iac-cicd also sets the backend's
encrypt = true flag, which additionally requests SSE on every state write;
for backend: r2 it's left false, R2's S3-compatible API doesn't support
that flag the same way AWS does. Either way, OpenTofu additionally supports
a native encryption {}
block for client-side encryption before state ever reaches the bucket, this
is OpenTofu-only (not available in Terraform) and is not configured by this
action, add it to your own terraform {} block if you want it; iac-cicd
does not touch that block.
- No bundled policy engine, no cost estimation.
policy-command(see Policy gate) is a hook to your own policy tool, not a built-in one. Drift detection isn't a special mode either, it's the same plan primitives on a schedule, see Drift detection. If you need cost estimation, look at a full platform (Scalr, Terrakube). - No generic multi-provider backend abstraction. R2 and AWS S3 are the two
tuned targets; other S3-compatible providers work through the
endpointescape hatch on a best-effort basis, see "Other S3-compatible providers" above. - Does not checkout your repo,
actions/checkoutstays the caller's responsibility, same convention ashashicorp/setup-terraform.
MIT