diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7f8c0ae --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,65 @@ +# Developing the Terraform Provider for Forgejo + +## Requirements + +- [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.0 +- [Go](https://golang.org/doc/install) >= 1.23 + +## Building the Provider + +1. Clone the repository +2. Enter the repository directory +3. Build the provider using the `make install` command: + +```shell +make install +``` + +### Directory Layout + +```shell +terraform-provider-forgejo/ +├── docker/ # Example Forgejo installation for local development +├── docs/ # Generated documentation +├── examples/ # Provider usage examples +├── internal/ # Provider source code and tests +└── tools/ # Scripts for generating documentation +``` + +## Adding Dependencies + +This provider uses [Go modules](https://github.com/golang/go/wiki/Modules). +Please see the Go documentation for the most up to date information about using Go modules. + +To add a new dependency `github.com/author/dependency` to your Terraform provider: + +```shell +go get github.com/author/dependency +go mod tidy +``` + +Then commit the changes to `go.mod` and `go.sum`. + +## Developing the Provider + +If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (see [Requirements](#requirements) above). + +To compile the provider, run `make install`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory. + +```shell +make install +``` + +To generate or update documentation, run `make generate`. + +```shell +make generate +``` + +In order to run the full suite of Acceptance tests, run `make testacc`. + +_Note:_ Acceptance tests create real resources, and often cost money to run. + +```shell +make testacc +``` diff --git a/README.md b/README.md index bea6983..c2cb0bd 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,16 @@ -# Terraform Forgejo Provider +# Terraform Provider for Forgejo -This repository contains a Terraform provider for [Forgejo](https://forgejo.org/) — self-hosted lightweight software forge. +This repository contains a [Terraform](https://www.terraform.io/) provider for [Forgejo](https://forgejo.org/) — self-hosted lightweight software forge. ## Contents -It is in a **very early** stage and currently contains the following... +The Forgejo Terraform Provider allows managing resources within Forgejo. It is in an **early** stage and currently provides the following... Resources: - `forgejo_organization` ([documentation](docs/resources/organization.md)) - `forgejo_repository` ([documentation](docs/resources/repository.md)) +- `forgejo_user` ([documentation](docs/resources/user.md)) Data Sources: @@ -17,112 +18,102 @@ Data Sources: - `forgejo_repository` ([documentation](docs/data-sources/repository.md)) - `forgejo_user` ([documentation](docs/data-sources/user.md)) -### Directory Layout - -```shell -terraform-provider-forgejo/ -├── docker/ # Example Forgejo installation for local development -├── docs/ # Generated documentation -├── examples/ # Provider usage examples -├── internal/ # Provider source code and tests -└── tools/ # Scripts for generating documentation -``` +## Using the Provider -## Requirements +Import the provider into your Terraform configuration: -- [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.0 -- [Go](https://golang.org/doc/install) >= 1.23 +```terraform +terraform { + required_providers { + forgejo = { + source = "svalabs/forgejo" + } + } +} +``` -## Building the Provider +There are two methods for authenticating to the Forgejo API: using an API token, or with username and password. -1. Clone the repository -2. Enter the repository directory -3. Build the provider using the Go `install` command: +It is recommended to supply an API token to authenticate with a given Forgejo host: -```shell -go install +```terraform +provider "forgejo" { + host = "http://localhost:3000" + api_token = "1234567890abcdefghijklmnopqrstuvwxyz1234" + # alternatively, use the FORGEJO_API_TOKEN environment variable +} ``` -## Adding Dependencies +Alternatively, supply username and password to authenticate: -This provider uses [Go modules](https://github.com/golang/go/wiki/Modules). -Please see the Go documentation for the most up to date information about using Go modules. +```terraform +provider "forgejo" { + host = "http://localhost:3000" + username = "admin" + password = "passw0rd" + # alternatively, use the FORGEJO_USERNAME / FORGEJO_PASSWORD environment variables +} +``` -To add a new dependency `github.com/author/dependency` to your Terraform provider: +A personal repository can be created like so: -```shell -go get github.com/author/dependency -go mod tidy +```terraform +resource "forgejo_repository" "example" { + name = "new_personal_repo" + description = "Purely for testing..." +} ``` -Then commit the changes to `go.mod` and `go.sum`. - -## Using the Provider +A user repository can be created like so (requires administrative privileges): ```terraform -terraform { - required_providers { - forgejo = { - source = "registry.terraform.io/svalabs/forgejo" - } - } +resource "forgejo_user" "example" { + name = "new_user" } -provider "forgejo" { - host = "http://localhost:3000" - api_token = "1234567890abcdefghijklmnopqrstuvwxyz1234" +resource "forgejo_repository" "example" { + owner = forgejo_user.example.name + name = "new_user_repo" + description = "Purely for testing..." } +``` -data "forgejo_organization" "example" { - name = "existing_org" -} +A organization repository can be created like so: +```terraform resource "forgejo_organization" "example" { - name = "new_org" - full_name = "Terraform Test Org" - description = "Purely for testing..." - website = "https://forgejo.org/" - location = "Mêlée Island" - visibility = "private" + name = "new_org" } -data "forgejo_repository" "example" { - owner = {} - name = "existing_repo" +resource "forgejo_repository" "example" { + owner = forgejo_organization.example.name + name = "new_org_repo" + description = "Purely for testing..." } +``` + +These examples create repositories with most attributes set to their default values. Many settings can be customized: +```terraform resource "forgejo_repository" "example" { - owner = {} - name = "new_repo" + owner = forgejo_organization.example.name + name = "new_org_repo" description = "Purely for testing..." private = true default_branch = "dev" auto_init = true -} + trust_model = "collaborator" -data "forgejo_user" "example" { - login = "existing_user" + 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. -## Developing the Provider - -If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (see [Requirements](#requirements) above). - -To compile the provider, run `go install`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory. - -To generate or update documentation, run `make generate`. - -In order to run the full suite of Acceptance tests, run `make testacc`. - -_Note:_ Acceptance tests create real resources, and often cost money to run. - -```shell -make testacc -``` - ## Copyright and License Copyright (c) 2024 SVA System Vertrieb Alexander GmbH. diff --git a/docs/data-sources/organization.md b/docs/data-sources/organization.md index c6da8a2..c29f484 100644 --- a/docs/data-sources/organization.md +++ b/docs/data-sources/organization.md @@ -16,7 +16,7 @@ Forgejo organization data source terraform { required_providers { forgejo = { - source = "registry.terraform.io/svalabs/forgejo" + source = "svalabs/forgejo" } } } @@ -28,7 +28,6 @@ provider "forgejo" { data "forgejo_organization" "this" { name = "test1" } - output "debug" { value = data.forgejo_organization.this } diff --git a/docs/data-sources/repository.md b/docs/data-sources/repository.md index aa57174..34131d7 100644 --- a/docs/data-sources/repository.md +++ b/docs/data-sources/repository.md @@ -16,7 +16,7 @@ Forgejo repository data source terraform { required_providers { forgejo = { - source = "registry.terraform.io/svalabs/forgejo" + source = "svalabs/forgejo" } } } @@ -31,16 +31,16 @@ data "forgejo_repository" "user" { } name = "user_test_repo_1" } +output "user_debug" { + value = data.forgejo_repository.user +} + data "forgejo_repository" "org" { owner = { login = "test_org_1" } name = "org_test_repo_1" } - -output "user_debug" { - value = data.forgejo_repository.user -} output "org_debug" { value = data.forgejo_repository.org } diff --git a/docs/data-sources/user.md b/docs/data-sources/user.md index 6eba919..e842c62 100644 --- a/docs/data-sources/user.md +++ b/docs/data-sources/user.md @@ -16,7 +16,7 @@ Forgejo user data source terraform { required_providers { forgejo = { - source = "registry.terraform.io/svalabs/forgejo" + source = "svalabs/forgejo" } } } @@ -28,7 +28,6 @@ provider "forgejo" { data "forgejo_user" "this" { login = "achim" } - output "debug" { value = data.forgejo_user.this } diff --git a/docs/index.md b/docs/index.md index c9466d7..f2e122e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,7 +16,7 @@ Terraform provider for Forgejo — self-hosted lightweight software forge terraform { required_providers { forgejo = { - source = "registry.terraform.io/svalabs/forgejo" + source = "svalabs/forgejo" } } } @@ -27,18 +27,16 @@ provider "forgejo" { username = "achim" password = "password" } +data "forgejo_organization" "username" { + provider = forgejo.username + name = "test1" +} provider "forgejo" { alias = "apiToken" host = "http://localhost:3000" api_token = "c754bf42c0728e3031e8245a70dbdda0419aff44" } - -data "forgejo_organization" "username" { - provider = forgejo.username - name = "test1" -} - data "forgejo_organization" "apiToken" { provider = forgejo.apiToken name = "test1" diff --git a/docs/resources/organization.md b/docs/resources/organization.md index 3d4700e..5854288 100644 --- a/docs/resources/organization.md +++ b/docs/resources/organization.md @@ -16,7 +16,7 @@ Forgejo organization resource terraform { required_providers { forgejo = { - source = "registry.terraform.io/svalabs/forgejo" + source = "svalabs/forgejo" } } } @@ -26,20 +26,20 @@ provider "forgejo" { } resource "forgejo_organization" "defaults" { - name = "tftest_defaults" + name = "tftest_org_defaults" } +output "debug_defaults" { + value = forgejo_organization.defaults +} + resource "forgejo_organization" "non_defaults" { - name = "tftest_non_defaults" + name = "tftest_org_non_defaults" full_name = "Terraform Test Org with non-default attributes" description = "Purely for testing..." website = "https://forgejo.org/" location = "Mêlée Island" visibility = "private" } - -output "debug_defaults" { - value = forgejo_organization.defaults -} output "debug_non_defaults" { value = forgejo_organization.non_defaults } @@ -54,7 +54,6 @@ output "debug_non_defaults" { ### Optional -- `avatar_url` (String) Avatar URL of the organization. - `description` (String) Description of the organization. - `full_name` (String) Full name of the organization. - `location` (String) Location of the organization. @@ -63,4 +62,5 @@ output "debug_non_defaults" { ### Read-Only +- `avatar_url` (String) Avatar URL of the organization. - `id` (Number) Numeric identifier of the organization. diff --git a/docs/resources/repository.md b/docs/resources/repository.md index aef3c1a..e2d1fea 100644 --- a/docs/resources/repository.md +++ b/docs/resources/repository.md @@ -16,7 +16,7 @@ Forgejo repository resource terraform { required_providers { forgejo = { - source = "registry.terraform.io/svalabs/forgejo" + source = "svalabs/forgejo" } } } @@ -25,15 +25,20 @@ provider "forgejo" { host = "http://localhost:3000" } +# +# Personal repository +# resource "forgejo_repository" "personal_defaults" { - owner = {} - name = "personal_tftest_defaults1" + name = "personal_tftest_defaults" } +output "personal_debug_defaults" { + value = forgejo_repository.personal_defaults +} + resource "forgejo_repository" "personal_non_defaults" { - owner = {} - name = "personal_tftest_non_defaults" - description = "Terraform Test Repo owned by user with non-default attributes" - # website = "http://localhost:3000" + name = "personal_tftest_non_defaults" + description = "Terraform Test Repo owned by user with non-default attributes" + website = "http://localhost:3000" private = true template = true default_branch = "custom" @@ -41,21 +46,38 @@ resource "forgejo_repository" "personal_non_defaults" { auto_init = false readme = "Default" trust_model = "collaborator" + archived = true + + internal_tracker = { + enable_time_tracker = false + allow_only_contributors_to_track_time = false + enable_issue_dependencies = false + } +} +output "personal_debug_non_defaults" { + value = forgejo_repository.personal_non_defaults +} + +# +# Organization repository +# +resource "forgejo_organization" "owner" { + name = "tftest_org" } resource "forgejo_repository" "org_defaults" { - owner = { - login = "test_org_1" - } - name = "org_tftest_defaults" + owner = forgejo_organization.owner.name + name = "org_tftest_defaults" } +output "org_debug_defaults" { + value = forgejo_repository.org_defaults +} + resource "forgejo_repository" "org_non_defaults" { - owner = { - login = "test_org_1" - } - name = "org_tftest_non_defaults" - description = "Terraform Test Repo owned by org with non-default attributes" - # website = "http://localhost:3000" + owner = forgejo_organization.owner.name + name = "org_tftest_non_defaults" + description = "Terraform Test Repo owned by org with non-default attributes" + website = "http://localhost:3000" private = true template = true default_branch = "custom" @@ -63,20 +85,57 @@ resource "forgejo_repository" "org_non_defaults" { auto_init = false readme = "Default" trust_model = "collaborator" + archived = true + + internal_tracker = { + enable_time_tracker = false + allow_only_contributors_to_track_time = false + enable_issue_dependencies = false + } +} +output "org_debug_non_defaults" { + value = forgejo_repository.org_non_defaults } -output "personal_debug_defaults" { - value = forgejo_repository.personal_defaults +# +# User repository +# +resource "forgejo_user" "owner" { + login = "tftest_user" + email = "tftest_user@localhost.localdomain" + password = "passw0rd" } -output "personal_debug_non_defaults" { - value = forgejo_repository.personal_non_defaults + +resource "forgejo_repository" "user_defaults" { + owner = forgejo_user.owner.login + name = "user_tftest_defaults" +} +output "user_debug_defaults" { + value = forgejo_repository.user_defaults } -output "org_debug_defaults" { - value = forgejo_repository.org_defaults +resource "forgejo_repository" "user_non_defaults" { + owner = forgejo_user.owner.login + name = "user_tftest_non_defaults" + description = "Terraform Test Repo owned by user with non-default attributes" + website = "http://localhost:3000" + private = true + template = true + default_branch = "custom" + issue_labels = "Default" + auto_init = false + readme = "Default" + trust_model = "collaborator" + archived = true + + internal_tracker = { + enable_time_tracker = false + allow_only_contributors_to_track_time = false + enable_issue_dependencies = false + } } -output "org_debug_non_defaults" { - value = forgejo_repository.org_non_defaults +output "user_debug_non_defaults" { + value = forgejo_repository.user_non_defaults } ``` @@ -86,17 +145,33 @@ output "org_debug_non_defaults" { ### Required - `name` (String) Name of the repository. -- `owner` (Attributes) Owner of the repository. (see [below for nested schema](#nestedatt--owner)) ### Optional +- `allow_merge_commits` (Boolean) Allowed to create merge commit? +- `allow_rebase` (Boolean) Allowed to rebase then fast-forward? +- `allow_rebase_explicit` (Boolean) Allowed to rebase then create merge commit? +- `allow_squash_merge` (Boolean) Allowed to create squash commit? +- `archived` (Boolean) Is the repository archived? - `auto_init` (Boolean) Whether the repository should be auto-intialized? - `default_branch` (String) Default branch of the repository. - `description` (String) Description of the repository. +- `external_tracker` (Attributes) Settings for external issue tracker. (see [below for nested schema](#nestedatt--external_tracker)) +- `external_wiki` (Attributes) Settings for external wiki. (see [below for nested schema](#nestedatt--external_wiki)) - `gitignores` (String) Gitignores to use +- `has_actions` (Boolean) Are integrated CI/CD pipelines enabled? +- `has_issues` (Boolean) Is the repository issue tracker enabled? +- `has_packages` (Boolean) Is the repository package registry enabled? +- `has_projects` (Boolean) Are repository projects enabled? +- `has_pull_requests` (Boolean) Are repository pull requests enabled? +- `has_releases` (Boolean) Are repository releases enabled? +- `has_wiki` (Boolean) Is the repository wiki enabled? +- `ignore_whitespace_conflicts` (Boolean) Are whitespace conflicts ignored? +- `internal_tracker` (Attributes) Settings for built-in issue tracker. (see [below for nested schema](#nestedatt--internal_tracker)) - `issue_labels` (String) Issue Label set to use - `license` (String) License to use -- `parent_id` (Number) Numeric identifier of the parent repository. +- `mirror_interval` (String) Mirror interval of the repository. +- `owner` (String) Owner of the repository. - `private` (Boolean) Is the repository private? - `readme` (String) Readme of the repository to create - `template` (Boolean) Is the repository a template? @@ -105,65 +180,35 @@ output "org_debug_non_defaults" { ### Read-Only -- `allow_merge_commits` (Boolean) Allowed to create merge commit? -- `allow_rebase` (Boolean) Allowed to rebase then fast-forward? -- `allow_rebase_explicit` (Boolean) Allowed to rebase then create merge commit? -- `allow_squash_merge` (Boolean) Allowed to create squash commit? -- `archived` (Boolean) Is the repository archived? - `avatar_url` (String) Avatar URL of the repository. - `clone_url` (String) Clone URL of the repository. - `created_at` (String) Time at which the repository was created. - `default_merge_style` (String) Default merge style of the repository. - `empty` (Boolean) Is the repository empty? -- `external_tracker` (Attributes) Settings for external issue tracker. (see [below for nested schema](#nestedatt--external_tracker)) -- `external_wiki` (Attributes) Settings for external wiki. (see [below for nested schema](#nestedatt--external_wiki)) - `fork` (Boolean) Is the repository a fork? - `forks_count` (Number) Number of forks of the repository. - `full_name` (String) Full name of the repository. -- `has_actions` (Boolean) Are integrated CI/CD pipelines enabled? -- `has_issues` (Boolean) Is the repository issue tracker enabled? -- `has_packages` (Boolean) Is the repository package registry enabled? -- `has_projects` (Boolean) Are repository projects enabled? -- `has_pull_requests` (Boolean) Are repository pull requests enabled? -- `has_releases` (Boolean) Are repository releases enabled? -- `has_wiki` (Boolean) Is the repository wiki enabled? - `html_url` (String) HTML URL of the repository. - `id` (Number) Numeric identifier of the repository. -- `ignore_whitespace_conflicts` (Boolean) Are whitespace conflicts ignored? - `internal` (Boolean) Is the repository internal? -- `internal_tracker` (Attributes) Settings for built-in issue tracker. (see [below for nested schema](#nestedatt--internal_tracker)) - `mirror` (Boolean) Is the repository a mirror? -- `mirror_interval` (String) Mirror interval of the repository. - `mirror_updated` (String) Time at which the repository mirror was updated. - `open_issues_count` (Number) Number of open issues of the repository. - `open_pr_counter` (Number) Number of open pull requests of the repository. - `original_url` (String) Original URL of the repository. +- `parent_id` (Number) Numeric identifier of the parent repository. - `permissions` (Attributes) Permissions of the repository. (see [below for nested schema](#nestedatt--permissions)) - `release_counter` (Number) Number of releases of the repository. - `size` (Number) Size of the repository in KiB. - `ssh_url` (String) SSH URL of the repository. - `stars_count` (Number) Number of stars of the repository. +- `updated_at` (String) Time at which the repository was updated. - `watchers_count` (Number) Number of watchers of the repository. - -### Nested Schema for `owner` - -Optional: - -- `login` (String) Name of the user. - -Read-Only: - -- `email` (String) Email address of the user. -- `full_name` (String) Full name of the user. -- `id` (Number) Numeric identifier of the user. -- `login_name` (String) Login name of the user. - - ### Nested Schema for `external_tracker` -Read-Only: +Optional: - `external_tracker_format` (String) External issue tracker URL format. - `external_tracker_style` (String) External issue tracker number format. @@ -173,7 +218,7 @@ Read-Only: ### Nested Schema for `external_wiki` -Read-Only: +Optional: - `external_wiki_url` (String) URL of external wiki. @@ -181,7 +226,7 @@ Read-Only: ### Nested Schema for `internal_tracker` -Read-Only: +Optional: - `allow_only_contributors_to_track_time` (Boolean) Let only contributors track time. - `enable_issue_dependencies` (Boolean) Enable dependencies for issues and pull requests. diff --git a/docs/resources/user.md b/docs/resources/user.md new file mode 100644 index 0000000..41249e4 --- /dev/null +++ b/docs/resources/user.md @@ -0,0 +1,88 @@ +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "forgejo_user Resource - forgejo" +subcategory: "" +description: |- + Forgejo user resource +--- + +# forgejo_user (Resource) + +Forgejo user resource + +## Example Usage + +```terraform +terraform { + required_providers { + forgejo = { + source = "svalabs/forgejo" + } + } +} + +provider "forgejo" { + host = "http://localhost:3000" +} + +resource "forgejo_user" "defaults" { + login = "tftest_user_defaults" + email = "tftest_user_defaults@localhost.localdomain" + password = "passw0rd" +} +output "debug_defaults" { + value = forgejo_user.defaults + sensitive = true +} + +resource "forgejo_user" "non_defaults" { + login = "tftest_user_non_defaults" + email = "tftest_user_non_defaults@localhost.localdomain" + password = "passw0rd" + full_name = "Terraform Test User with non-default attributes" + description = "Purely for testing..." + website = "https://forgejo.org/" + location = "Mêlée Island" + visibility = "private" +} +output "debug_non_defaults" { + value = forgejo_user.non_defaults + sensitive = true +} +``` + + +## Schema + +### Required + +- `email` (String) Email address of the user. +- `login` (String) Name of the user. +- `password` (String, Sensitive) Password of the user. + +### Optional + +- `active` (Boolean) Is the user active? +- `admin` (Boolean) Is the user an administrator? +- `description` (String) Description of the user. +- `full_name` (String) Full name of the user. +- `location` (String) Location of the user. +- `login_name` (String) Login name of the user. +- `must_change_password` (Boolean) Require user to change password? +- `prohibit_login` (Boolean) Are user logins prohibited? +- `restricted` (Boolean) Is the user restricted? +- `send_notify` (Boolean) Send notification to administrators? +- `source_id` (Number) Numeric identifier of the user's authentication source. +- `visibility` (String) Visibility of the user. +- `website` (String) Website of the user. + +### Read-Only + +- `avatar_url` (String) Avatar URL of the user. +- `created` (String) Date and time of user creation. +- `followers_count` (Number) Number of following users. +- `following_count` (Number) Number of users followed. +- `id` (Number) Numeric identifier of the user. +- `language` (String) Locale of the user. +- `last_login` (String) Date and time of last login. +- `starred_repos_count` (Number) Number of starred repositories.