Terraform Provider for Forgejo

This repository contains a Terraform and OpenTofu provider for Forgejo — self-hosted lightweight software forge. The project is based on the awesome Forgejo SDK for Go by Martijn van der Kleijn. Thanks, Martijn, for the heavy lifting!

Contents

The Forgejo Terraform/OpenTofu Provider allows managing resources and data source within Forgejo instances. It currently provides the following...

Resources:

• forgejo_branch_protection (documentation)
• forgejo_collaborator (documentation)
• forgejo_deploy_key (documentation)
• forgejo_gpg_key (documentation)
• forgejo_organization (documentation)
• forgejo_organization_action_secret (documentation)
• forgejo_organization_action_variable (documentation)
• forgejo_repository (documentation)
• forgejo_repository_action_secret (documentation)
• forgejo_repository_action_variable (documentation)
• forgejo_ssh_key (documentation)
• forgejo_team (documentation)
• forgejo_team_member (documentation)
• forgejo_user (documentation)

Data Sources:

• forgejo_collaborator (documentation)
• forgejo_deploy_key (documentation)
• forgejo_gpg_key (documentation)
• forgejo_organization (documentation)
• forgejo_organization_action_variable (documentation)
• forgejo_repository (documentation)
• forgejo_repository_action_variable (documentation)
• forgejo_ssh_key (documentation)
• forgejo_team (documentation)
• forgejo_team_member (documentation)
• forgejo_user (documentation)

Using the Provider

Import the provider into your Terraform/OpenTofu configuration:

terraform {
  required_providers {
    forgejo = {
      source  = "svalabs/forgejo"
      version = "~> 1.4.0"
    }
  }
}

There are two methods for authenticating to the Forgejo API: using an API token, or with username and password.

It is recommended to supply an API token to authenticate with a given Forgejo host:

provider "forgejo" {
  host      = "http://localhost:3000"
  api_token = "<<<your_api_key>>>"
  # ...or use the FORGEJO_API_TOKEN environment variable
}

API tokens can be generated through the Forgejo web interface, by navigating to Settings → Applications → Access tokens → Generate new token.

The following API token permissions are required:

• write:organization
• write:repository
• write:user

Optionally, for administrative privileges (required to manage users, user repositories, and user SSH keys):

• write:admin

Alternatively, supply username and password to authenticate:

provider "forgejo" {
  host     = "http://localhost:3000"
  username = "<<<your_username>>>"
  password = "<<<your_password>>>"
  # ...or use the FORGEJO_USERNAME / FORGEJO_PASSWORD environment variables
}

Important: The Forgejo API client does not (currently) allow ignoring certificate errors. When connecting through https://, the Forgejo host must supply certificates trusted by the Terraform/OpenTofu host. Hence, self-signed certificates must be imported locally. This can be achieved by running the following command:

echo quit | openssl s_client -showcerts -servername <<<forgejo_host>>> -connect <<<forgejo_host>>> > /etc/ssl/certs/cacert.pem

A personal repository can be created like so:

resource "forgejo_repository" "example" {
  name        = "new_personal_repo"
  description = "Purely for testing..."
}

A user repository can be created like so (requires administrative privileges):

resource "forgejo_user" "owner" {
  login = "new_user"
}

resource "forgejo_repository" "example" {
  owner       = forgejo_user.owner.login
  name        = "new_user_repo"
  description = "Purely for testing..."
}

An organization repository can be created like so:

resource "forgejo_organization" "owner" {
  name = "new_org"
}

resource "forgejo_repository" "example" {
  owner       = forgejo_organization.owner.name
  name        = "new_org_repo"
  description = "Purely for testing..."
}

A clone repository can be created like so:

resource "forgejo_repository" "clone" {
  name       = "clone_test_repo"
  clone_addr = "https://github.com/svalabs/terraform-provider-forgejo"
  mirror     = false
}

A pull mirror repository can be created like so:

resource "forgejo_repository" "mirror" {
  name            = "mirror_test_repo"
  clone_addr      = "https://github.com/svalabs/terraform-provider-forgejo"
  mirror          = true
  mirror_interval = "12h0m0s"
}

These examples create repositories with most attributes set to their default values. However, many settings can be customized:

resource "forgejo_repository" "example" {
  owner          = forgejo_organization.owner.name
  name           = "new_org_repo"
  description    = "Purely for testing..."
  private        = true
  default_branch = "dev"
  auto_init      = true
  trust_model    = "collaborator"

  internal_tracker = {
    enable_time_tracker                   = false
    allow_only_contributors_to_track_time = false
    enable_issue_dependencies             = false
  }
}

Refer to the examples/ directory for more usage examples.

Importing Existing Resources

Some resources support import into Terraform state. Importing is useful for bringing existing, manually created resources under Terraform management. Each resource defines its own import identifier, which uniquely identifies the resource to be imported:

Resource	Import Identifier
forgejo_repository	<<<repo_owner>>>/<<<repo_name>>>
forgejo_branch_protection	<<<repo_owner>>>/<<<repo_name>>>/<<<branch>>>
forgejo_user	<<<login>>>
forgejo_team	<<<org_name>>>/<<<team_name>>>

Refer to the examples/ directory for more import examples.

Preventing Accidental Destruction

Once repositories contain important data, you need to protect them against accidental destruction. Terraform will destroy and recreate a repository if any of the create-only attributes (auto_init, gitignores, license, etc.) are modified, resulting in permanent data loss.

To prevent this, add the prevent_destroy lifecycle meta-argument to critical (repository) resources:

resource "forgejo_repository" "important" {
  ...

  lifecycle {
    prevent_destroy = true
  }
}

Note: With prevent_destroy enabled, Terraform will refuse to destroy the resource and return an error if destruction is attempted. You must explicitly remove this setting before the resource can be destroyed.

Troubleshooting

Error: failed to verify certificate: certificate signed by unknown authority

In case of the following error message:

Error: Unable to Create Forgejo API Client

    An unexpected error occurred when creating the Forgejo API client. If the
    error is not clear, please contact the provider developers.

    Forgejo Client Error: Get "https://.../api/v1/version":
    tls: failed to verify certificate: x509: certificate signed by unknown
    authority

Extract the self-signed certificate from the Forgejo host and import it locally:

echo quit | openssl s_client -showcerts -servername <<<forgejo_host>>> -connect <<<forgejo_host>>> > /etc/ssl/certs/cacert.pem

Error: token does not have at least one of required scope(s)

In case of the following error message:

Error: Unable to get repository by id

    Unknown error: token does not have at least one of required scope(s):
    [read:repository]

Re-generate the API token used for authentication, and make sure to select the following permissions:

• write:organization
• write:repository
• write:user
• Optional, for managing users, user repositories, and user SSH keys: write:admin

Developing & Contributing to the Provider

The CONTRIBUTING.md file is a basic outline on how to build and develop the provider.

Copyright and License

Copyright (c) 2024 SVA System Vertrieb Alexander GmbH.

Released under the terms of the Mozilla Public License (MPL-2.0).