Skip to main content

Quick reference​

Terraform state buckets are created automatically when an IaC repo is created via governance.

  1. Issue → template "Request new repository" → category iac
  2. Label approve-repo → 3 buckets created (dev, qa, prd)
  3. safe-settings creates the repo with the pre-configured template
  4. First PR with Terraform → automatic plan works immediately

There are no manual bootstrap steps. See ADR-0012 for the full decision.

When to use​

When a new infrastructure stack managed by the Terraflow pipeline is needed. The bootstrap happens automatically as part of the repository creation flow.

Preconditions​

Procedure​

1. Create the repository via governance​

  1. Go to platform-settings → Issues → New Issue → select "Request new repository".
  2. Select category iac.
  3. Enter the descriptive name (without prefix) — e.g., distribution. The final repo will be iac-distribution.
  4. Add the approve-repo label to the issue once the summary table looks correct.

2. Auto-bootstrap (automatic)​

The approve-repo.yml workflow performs these steps automatically:

  1. Authenticates with GCP using platform-bootstrap@eigenoid-{env} via WIF (3 times, once per project).

  2. Creates 3 buckets following the convention:

    EnvironmentBucket
    deveigenoid-2cea55-{stack}-tfstate-dev
    qaeigenoid-2cea55-{stack}-tfstate-qa
    prdeigenoid-2cea55-{stack}-tfstate-prd

    Each bucket has versioning enabled and public access prevention.

  3. Updates the registry (.github/state-buckets.json) with the new buckets.

  4. Comments on the issue with a table of the created buckets.

  5. Pushes the config YAML → safe-settings creates the repo from the iac-template template.

3. Verify​

The repo is created fully pre-configured (the template includes terraflow.yaml, backend configs, workflow). Verify:

# Verify the repo exists
gh repo view eigenoid/iac-NAME

# Verify created buckets
for env in dev qa prd; do
  gcloud storage buckets describe gs://eigenoid-2cea55-STACK-tfstate-$env 2>&1 | head -3
done

# Verify the registry
gh api repos/eigenoid/platform-settings/contents/.github/state-buckets.json \
  --jq '.content' | base64 -d | jq '."iac-NAME"'
bash

4. First PR​

  1. Clone the repo: git clone https://github.com/eigenoid/iac-NAME.git
  2. Create a layer with resources (or use the example layer from the template).
  3. Open a PR → the automatic plan should run against dev.
  4. Verify that the bot comments with the plan result.

Troubleshooting​

Buckets were not created​

  1. Check logs: go to platform-settings → Actions → find the approve-repo workflow run.
  2. Check the SA: platform-bootstrap@eigenoid-{env} must exist with roles/storage.admin in each project.
  3. Re-trigger: remove the approve-repo label, wait a few seconds, add it again.
Config already exists

If the workflow failed after pushing the config YAML (partial run), you must delete .github/repos/{name}.yml before re-triggering. The workflow detects that the config already exists and fails with an error.

Error: "Permission denied" on Terraform apply via CI​

The Service Account terraform-ci@eigenoid-{env} needs the appropriate roles:

gcloud projects get-iam-policy eigenoid-{env} \
  --flatten="bindings[].members" \
  --filter="bindings.members:terraform-ci@" \
  --format="table(bindings.role)"
bash

Error: "Ignoring variable when applying a saved plan"​

A TF_VAR_iac_* variable changes between plan and apply (e.g., iac_run_id). The solution is to not declare that variable in Terraform — undeclared variables are silently ignored.

Error: Bot does not comment on the PR​

Check:

  1. Org secrets TERRAFLOW_BOT_CLIENT_ID and TERRAFLOW_BOT_PRIVATE_KEY exist.
  2. The GitHub App eigenoid-terraflow-bot is installed on the consumer repo.
  3. The App has Pull requests: Read & write permissions.

Error: "No plan run found" on /terraflow apply​

The slash command looks for a successful plan for the same commit SHA:

  1. A previous successful plan must exist (green check).
  2. There must be no new pushes to the PR after the plan (the SHA must match).

Emergency: manual bootstrap​

In case the auto-bootstrap does not work and buckets need to be created manually:

STACK=stack-name

for env in dev qa prd; do
  gcloud storage buckets create \
    gs://eigenoid-2cea55-${STACK}-tfstate-${env} \
    --project=eigenoid-${env} \
    --location=europe-west1 \
    --uniform-bucket-level-access \
    --pap

  gcloud storage buckets update \
    gs://eigenoid-2cea55-${STACK}-tfstate-${env} \
    --versioning
done
bash

Afterward, manually update .github/state-buckets.json in platform-settings.

Verification​

  • Repo iac-NAME exists and has the template applied.
  • 3 buckets created with correct naming and versioning enabled.
  • state-buckets.json has the repo entry.
  • Automatic plan runs on PRs to the consumer.
  • /terraflow apply applies changes correctly.
  • Bot comments with its identity (eigenoid-terraflow-bot[bot]).

References​