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}"
  }
}

Placeholder	Description
owner	The owner of the state (user or organization).
name	The name of the state.
username	Your Gitea username.
password	Your Gitea password or personal access 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}