Skip to content

The Terraform CDK GitHub Action allows you to run CDKTF as part of your CI/CD workflow

License

Notifications You must be signed in to change notification settings

hashicorp/terraform-cdk-action

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Terraform CDK GitHub Action

The Terraform CDK GitHub Action allows you to run CDKTF as part of your CI/CD workflow.

Inputs

parameter description required default
cdktfVersion The version of CDKTF to use false 0.20.9
terraformVersion The version of Terraform to use false 1.9.8
workingDirectory The directory to use for the project false ./
mode What action to take: synth-only runs only the synthesis, plan-only only runs a plan, auto-approve-apply runs a plan and then performs an apply, auto-approve-destroy runs a plan and then performs a destroy true
stackName The stack to run / plan, only required when the mode is plan-only or plan-and-apply false
terraformCloudToken The Terraform Cloud / Terraform Enterprise token to use false
githubToken The github token to use false
commentOnPr Whether to comment the plan / the status on the PR false true
updateComment Whether to update the last comment on the PR rather than adding a new comment false true
customNpxArgs The additional CLI arguments to pass to npx as part of the cdktf-cli execution. false
cdktfArgs The additional CLI arguments to pass to cdktf as part of the cdktf-cli execution. false
suppressOutput Whether to suppress the output of the action in PR comments false false

Example Configurations

The examples assume you have your provider credentials in Terraform Cloud and you are using remote execution to access the provider credentials or you are passing the provider credentials as environment variables through the env key on the action. Please don't use this action with the default local backend as the state might get lost and locking might not work.

Comment the plan of a stack on a PR

name: "Comment a Plan on a PR"

on: [pull_request]

permissions:
  contents: read
  pull-requests: write

jobs:
  terraform:
    name: "Terraform CDK Diff"
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: yarn install

      - name: Generate module and provider bindings
        run: npx cdktf-cli get

      # Remove this step if you don't have any
      - name: Run unit tests
        run: yarn test

      - name: Run Terraform CDK
        uses: hashicorp/terraform-cdk-action@v5
        with:
          cdktfVersion: 0.20.9
          terraformVersion: 1.9.8
          mode: plan-only
          stackName: my-stack
          terraformCloudToken: ${{ secrets.TF_API_TOKEN }}
          githubToken: ${{ secrets.GITHUB_TOKEN }}

Apply a stack after a PR is merged

name: "Apply Stack after PR is Merged"

on:
  push:
    branches:
      - main

permissions:
  contents: read
  pull-requests: write
  issues: read

jobs:
  terraform:
    name: "Terraform CDK Deploy"
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: yarn install

      - name: Generate module and provider bindings
        run: npx cdktf-cli get

      # Remove this step if you don't have any
      - name: Run unit tests
        run: yarn test

      - name: Run Terraform CDK
        uses: hashicorp/terraform-cdk-action@v5
        with:
          cdktfVersion: 0.20.9
          terraformVersion: 1.9.8
          mode: auto-approve-apply
          stackName: my-stack
          terraformCloudToken: ${{ secrets.TF_API_TOKEN }}
          githubToken: ${{ secrets.GITHUB_TOKEN }}

Synthesize on PRs

name: "Synth the CDKTF Application on PRs"

on: [pull_request]

permissions:
  contents: read
  pull-requests: write

jobs:
  terraform:
    name: "Terraform CDK Synth"
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: yarn install

      - name: Generate module and provider bindings
        run: npx cdktf-cli get

      # Remove this step if you don't have any
      - name: Run unit tests
        run: yarn test

      - name: Test the synth
        uses: hashicorp/terraform-cdk-action@v5
        with:
          cdktfVersion: 0.20.9
          terraformVersion: 1.9.8
          mode: synth-only
          stackName: my-stack

Limitations

This action is intended to be limited to a single stack. While you could pass * as the stack name and use multi-stack deployments, we don't currently support all the complexities of doing accurate plans across multiple dependent workspaces within the action.