How to Use Terraform with GitLab CI: Simple Guide

Use terraform commands inside a .gitlab-ci.yml file to automate infrastructure deployment with GitLab CI. Define stages like init, plan, and apply in the pipeline, and configure environment variables for authentication. This setup runs Terraform commands automatically on GitLab runners when you push code.

Syntax

The .gitlab-ci.yml file defines the pipeline stages and jobs. Each job runs Terraform commands like terraform init, terraform plan, and terraform apply. Use stages to order jobs, and variables to set environment variables such as cloud credentials. The script section contains the commands to run.

yaml

stages:
  - init
  - plan
  - apply

variables:
  TF_ROOT: "terraform"
  TF_VAR_example: "value"

terraform_init:
  stage: init
  script:
    - terraform -chdir=$TF_ROOT init

terraform_plan:
  stage: plan
  script:
    - terraform -chdir=$TF_ROOT plan
  dependencies:
    - terraform_init

terraform_apply:
  stage: apply
  script:
    - terraform -chdir=$TF_ROOT apply -auto-approve
  dependencies:
    - terraform_plan
  when: manual

Example

This example shows a simple GitLab CI pipeline that initializes Terraform, creates a plan, and applies it manually. It assumes your Terraform files are in a terraform folder. The apply stage is manual to prevent accidental changes.

yaml

stages:
  - init
  - plan
  - apply

variables:
  TF_ROOT: "terraform"

terraform_init:
  stage: init
  script:
    - terraform -chdir=$TF_ROOT init

terraform_plan:
  stage: plan
  script:
    - terraform -chdir=$TF_ROOT plan
  dependencies:
    - terraform_init

terraform_apply:
  stage: apply
  script:
    - terraform -chdir=$TF_ROOT apply -auto-approve
  dependencies:
    - terraform_plan
  when: manual

Output

Running with gitlab-runner 15.10.0 (abcdefg)
Preparing the environment
Running terraform_init stage
Terraform has been successfully initialized!
Running terraform_plan stage
Terraform plan shows no changes.
Waiting for manual action to apply changes
Running terraform_apply stage
Terraform apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Common Pitfalls

• Not setting cloud provider credentials as protected variables in GitLab causes authentication failures.
• Running terraform apply automatically can cause unwanted changes; use when: manual to control this.
• Not using dependencies can cause jobs to run out of order or without required artifacts.
• Forgetting to specify the Terraform working directory with -chdir if your files are not in the root.

yaml

Wrong:
terraform_apply:
  stage: apply
  script:
    - terraform apply -auto-approve
  when: always

Right:
terraform_apply:
  stage: apply
  script:
    - terraform -chdir=$TF_ROOT apply -auto-approve
  when: manual
  dependencies:
    - terraform_plan

Quick Reference

Remember these key points when using Terraform with GitLab CI:

• Define stages for init, plan, and apply.
• Use variables for paths and credentials.
• Use dependencies to order jobs.
• Set when: manual on apply to avoid accidental changes.
• Store sensitive data in GitLab CI protected variables.

Key Takeaways

Use a .gitlab-ci.yml file to run Terraform commands in stages: init, plan, and apply.

Set cloud credentials as protected variables in GitLab to authenticate Terraform.

Use 'when: manual' on apply stage to control infrastructure changes safely.

Specify Terraform working directory with '-chdir' if your files are not in the root.

Use dependencies to ensure jobs run in the correct order.