Skip to content
play

GitHub Action

terraform-state

v2 Latest version

terraform-state

play

terraform-state

Store Terraform state for your GitHub Actions as an encrypted artifact or repository file

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: terraform-state

              
  uses: BadgerHobbs/terraform-state@v2
Learn more about this action in BadgerHobbs/terraform-state

Choose a version

Terraform State

Artifact Artifact Encrypted Repository File Repository File Encrypted

Terraform State is a GitHub Action that manages the storage of your Terraform state file as an (optionally) encrypted artifact or repository file. This makes it easier for you to handle your state file securely and efficiently within GitHub, not requiring a 3rd party service.

Getting Started

Below you can find documentation on how to setup and use the terraform-state GitHub Action.

Setup

The following inputs are used by the GitHub Action.

Variable Description Required Default
encryption_key AES-256 Encryption key used to encrypt/decrypt the Terraform state file. False N/A
operation Specifies if the operation is to download or upload the Terraform state file. Options: download, upload True N/A
location Specifies the storage location of the Terraform state file. Options: repository, artifact. True N/A
directory Directory of the Terraform state file. False "."
github_token GitHub Access Token used to retrieve latest artifact. False N/A

It is recommended to use GitHub secrets to store the encryption_key and github_token.

Usage

The following examples illustrate the best practices to use terraform-state to handle various scenarios of uploading and downloading a Terraform state file.

In addition, please note that while storing encrypted state within the repository ensures reasonable security, it is not recommended specifically for public repositories. Preferably, you should use artifacts. However, keep in mind that artifacts by default only last 90 days (can be changed in the repository settings).

When storing the Terraform state within the repository, changes are commited to the current branch. To prevent endless loops when the GitHub Action is triggered to run on push, configure the following.

push:
  paths-ignore:
    - "**.tfstate"
    - "**.tfstate.encrypted"

Artifact

Please see this Example Workflow.

- name: Download Artifact
    uses: badgerhobbs/terraform-state@v2
    with:
        operation: download
        location: artifact
        github_token: ${{ secrets.gh_access_token }}
    continue-on-error: true

- name: Upload Artifact
    uses: badgerhobbs/terraform-state@v2
    with:
        operation: upload
        location: artifact
        github_token: ${{ secrets.gh_access_token }}

Artifact Encrypted

Please see this Example Workflow.

- name: Download Encrypted Artifact & Decrypt Artifact
    uses: badgerhobbs/terraform-state@v2
    with:
        encryption_key: ${{ secrets.encryption_key }}
        operation: download
        location: artifact
        github_token: ${{ secrets.gh_access_token }}
    continue-on-error: true

- name: Encrypt Artifact & Upload Encrypted Artifact
    uses: badgerhobbs/terraform-state@v2
    with:
        encryption_key: ${{ secrets.encryption_key }}
        operation: upload
        location: artifact
        github_token: ${{ secrets.gh_access_token }}

Repository File

Please see this Example Workflow.

- name: Commit Repository File
    uses: badgerhobbs/terraform-state@v2
    with:
        operation: upload
        location: repository

Repository File Encrypted

Please see this Example Workflow.

- name: Decrypt Repository File
    uses: badgerhobbs/terraform-state@v2
    with:
        encryption_key: ${{ secrets.encryption_key }}
        operation: download
        location: repository
    continue-on-error: true

- name: Encrypt and Commit Repository File
    uses: badgerhobbs/terraform-state@v2
    with:
        encryption_key: ${{ secrets.encryption_key }}
        operation: upload
        location: repository

Acknowledgments

Despite different approaches, the development of this GitHub Action was influenced by the previous work of:

License

The scripts and documentation in this project are released under the MIT License.