Terraform State Registry

Publish terraform states to sync it between multiple users or CI system.

Requirements​

To work with the Terraform State registry, you need to use Terraform or OpenTofu.

Configuring the package registry​

To use the Gitea Terraform State registry, you need to configure the http backend in your Terraform configuration.

terraform {
  backend "http" {
    address        = "https://gitea.example.com/api/packages/{owner}/terraform/state/{name}"
    lock_address   = "https://gitea.example.com/api/packages/{owner}/terraform/state/{name}/lock"
    unlock_address = "https://gitea.example.com/api/packages/{owner}/terraform/state/{name}/lock"
    lock_method    = "POST"
    unlock_method  = "DELETE"
    username       = "{username}"
    password       = "{password_or_token}"
  }
}

If you are using 2FA or OAuth use a personal access token instead of the password.

Initialize the backend​

After configuring the backend, you can initialize it with:

terraform init

Terraform will prompt you to migrate your state if you already have one locally.

State Locking​

Gitea supports state locking to prevent concurrent modifications. The lock_address and unlock_address should point to the /lock sub-route of your state URL.

• Locking: Performed via a POST request to {address}/lock.
• Unlocking: Performed via a DELETE request to {address}/lock.

Terraform handles these requests automatically when configured as shown above.

Encrypted state​

The state registry supports encrypted state.

State Versions and Management​

Gitea keeps track of your Terraform state versions. You can use the API to retrieve or delete specific versions.

Fetch state​

To fetch the latest version of a state:

curl --user {username}:{password_or_token} \
     https://gitea.example.com/api/packages/{owner}/terraform/state/{name}

To fetch a specific version by its serial number:

curl --user {username}:{password_or_token} \
     https://gitea.example.com/api/packages/{owner}/terraform/state/{name}/versions/{serial}

Delete state​

To delete the entire state and all its versions:

curl --user {username}:{password_or_token} -X DELETE \
     https://gitea.example.com/api/packages/{owner}/terraform/state/{name}

To delete a specific version by its serial number:

curl --user {username}:{password_or_token} -X DELETE \
     https://gitea.example.com/api/packages/{owner}/terraform/state/{name}/versions/{serial}