Terraform Provider for Forgejo

This repository contains a Terraform provider for Forgejo — self-hosted lightweight software forge.

Contents

The Forgejo Terraform Provider allows managing resources within Forgejo. It is in an early stage and currently provides the following...

Resources:

• forgejo_organization (documentation)
• forgejo_repository (documentation)
• forgejo_user (documentation)

Data Sources:

• forgejo_organization (documentation)
• forgejo_repository (documentation)
• forgejo_user (documentation)

Using the Provider

Import the provider into your Terraform configuration:

terraform {
  required_providers {
    forgejo = {
      source = "svalabs/forgejo"
      version = "~> 0.1.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 = "1234567890abcdefghijklmnopqrstuvwxyz1234"
  # ...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

Optional, for administrative privileges (required to manage users and user repositories):

• write:admin

Alternatively, supply username and password to authenticate:

provider "forgejo" {
  host     = "http://localhost:3000"
  username = "admin"
  password = "passw0rd"
  # ...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 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..."
}

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.

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 and user repositories: 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).