Managing Terraform State

Introduction

In certain scenarios it may be necessary to perform one-off actions on your terraform state files, for instance…

• force-unlocking the state
• importing manually created resources to the state
• removing resources you no longer wish to manage in state

For these scenarios we have supplied a Terraform State Management GitHub Action for managing your state files.

Using the GitHub Action

1. Navigate to the Terraform State Management GitHub Action
2. Select Run workflow
3. You will be presented with a series of options for the various operations available

Note: If you are managing the state for a component directory (i.e. a subfolder in terraform/environments/<application>) then you will need to supply the name of the relevant directory in the Component field.

For most users this can be left as the default root value

How to force unlock TF state

1. Select the unlock operation
2. Enter your application name e.g. apex
3. Select the relevant environment workspace e.g. development
4. Enter the state lock id e.g. f2aa1369-2236-3b89-5a03-db4de84b1234
5. Select Run Workflow
6. The workflow will commence and show a summary of the information supplied, after which a manual review is required.
7. If you are content to proceed select review deployments, select the relevant tick box for the environment and finally select Approve and deploy
8. The deployment will continue and unlock the state. If any errors are encountered you can review the logs for further info.

How to import resources into the TF state

Note: Before using this operation you need to add the resources you are intending to import to your terraform config on a feature branch

1. Select the import operation
2. Enter your application name e.g. apex
3. Select the relevant environment workspace e.g. development
4. Enter resource addresses as required (these must be comma separated when handling multiple resources)

• e.g. to import an s3 bucket/ec2 instance aws_s3_bucket.test_import_bucket,aws_instance.test_import_instance

1. Enter the resource IDs as required (again comma separated and must match the resource addresses order)

• e.g. test-s3-bucket-name,i-0c9c2b36e598cefea

1. Enter the name of the feature branch with your associated config for the imported resources
2. Select Run Workflow, and follow the same steps as above to review/deploy the changes
3. Once this has completed you can continue to raise a PR/merge your config changes as usual

How to remove resources from the TF state

1. Select the remove operation
2. Enter your application name e.g. apex
3. Select the relevant environment workspace e.g. development
4. Enter resource addresses as required (these must be comma separated when handling multiple resources)

• e.g. to remove an s3 bucket/ec2 instance aws_s3_bucket.test_import_bucket,aws_instance.test_import_instance

1. Select Run Workflow, and follow the same steps as above to review/deploy the changes

Troubleshooting

If any errors are encountered you can review the logs for more detailed information. If in doubt contact the Modernisation Platform team via the ask channel

This page was last reviewed on 29 August 2025. It needs to be reviewed again on 28 February 2026 by the page owner #modernisation-platform .