Update examples and test pipeline to fix build. Add additional documentation. Update terraform docs. (#112)

PR to fix the build again before proposing changes to enable https://gitea.com/gitea/terraform-provider-gitea/issues/111.

This is my first time contributing to a Terraform Provider, any thoughts or feedback will be greatly appreciated!

No functionality is changed, only the examples, test pipelines and docs, so I did not increment the version of the provider.  I am still a bit unsure about the lifecycle management of Terraform Providers. Should it be incremented anyway?

Co-authored-by: Boris van der Donck <[email protected]>
Reviewed-on: https://gitea.com/gitea/terraform-provider-gitea/pulls/112
Reviewed-by: techknowlogick <[email protected]>
Co-authored-by: BravoDeltaBD <[email protected]>
Co-committed-by: BravoDeltaBD <[email protected]>

Author: 2 people

.gitea/workflows/test.yml

@@ -16,8 +16,9 @@ jobs:
 
     - name: Terraform fmt
       id: fmt
-      run: terraform fmt -check
+      run: terraform fmt -check -diff -recursive
       continue-on-error: true
+      working-directory: examples
 
     - name: Terraform Init
       id: init

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to the Gitea Terraform Provider
+
+Thank you for your interest in contributing to the Gitea Terraform Provider! This document outlines the basic process to contribute effectively.
+
+## Getting Started
+
+1. **Fork the repository** on Gitea.
+2. **Clone your fork** locally.
+3. **Create a branch** for your changes.
+
+
+See also [Hashicorp's Terraform Provider tutorial](https://developer.hashicorp.com/terraform/tutorials/providers-plugin-framework/providers-plugin-framework-provider)
+
+## Testing your changes
+
+### Running a local Gitea instance
+
+```bash
+docker run -p 3000:3000 gitea/gitea:latest-rootless
+```
+
+Visit http://localhost:3000 and go through the setup:
+1. Url: http://localhost:3000
+2. Username: gitea_admin
+3. Password: gitea_admin
+4. Email: [email protected]
+
+### Using the local version of the Provider
+This involves 2 main steps:
+- `go install .` to install the provider binary.
+- Use .terraformrc file to point to that binary instead of the terraform registry.
+
+See Terraform docs on [development overrides for provider developers](https://developer.hashicorp.com/terraform/cli/config/config-file#development-overrides-for-provider-developers)
+
+Also see [this tutorial section](https://developer.hashicorp.com/terraform/tutorials/providers-plugin-framework/providers-plugin-framework-provider#prepare-terraform-for-local-provider-install) for a bit more context.
+
+Example linux `~/.terraformrc` file:
+```
+provider_installation {
+
+  dev_overrides {
+      "go-gitea/gitea" = "/home/<username>/go/bin"
+  }
+
+  # For all other providers, install them directly from their origin provider
+  # registries as normal. If you omit this, Terraform will _only_ use
+  # the dev_overrides block, and so no other providers will be available.
+  direct {}
+}
+```
+
+### Applying the example module
+
+With the local provider and the local Gitea instance set up properly as per above chapters, the example module can be applied:
+
+- navigate into `examples/`
+- run terraform commands
+
+
+

docs/index.md

@@ -16,26 +16,26 @@ description: |-
 terraform {
   required_providers {
     gitea = {
-      source = "go-gitea/gitea"
+      source  = "go-gitea/gitea"
       version = "0.6.0"
     }
   }
 }
 
 provider "gitea" {
-  base_url = var.gitea_url # optionally use GITEA_BASE_URL env var
+  base_url = var.gitea_url   # optionally use GITEA_BASE_URL env var
   token    = var.gitea_token # optionally use GITEA_TOKEN env var
 
   # Username/Password authentication is mutally exclusive with token authentication
   # username = var.username # optionally use GITEA_USERNAME env var
   # password = var.password # optionally use GITEA_PASSWORD env var
 
   # A file containing the ca certificate to use in case ssl certificate is not from a standard chain
-  cacert_file = var.cacert_file 
-  
+  cacert_file = var.cacert_file
+
   # If you are running a gitea instance with self signed TLS certificates
   # and you want to disable certificate validation you can deactivate it with this flag
-  insecure = false 
+  insecure = false
 }
 ```
 

docs/resources/git_hook.md

@@ -21,19 +21,19 @@ if you want to procede, you need to enable server side hooks as stated [here](ht
 ## Example Usage
 
 ```terraform
-resource "gitea_org" "test_org" {
-  name = "test-org"
+resource "gitea_org" "example" {
+  name = "git-hook-example-org"
 }
 
-resource "gitea_repository" "org_repo" {
-  username = gitea_org.test_org.name
-  name     = "org-test-repo"
+resource "gitea_repository" "example" {
+  username = gitea_org.example.name
+  name     = "git-hook-example-repo"
 }
 
 resource "gitea_git_hook" "org_repo_post_receive" {
   name    = "post-receive"
-  user    = gitea_org.test_org.name
-  repo    = gitea_repository.org_repo.name
+  user    = gitea_org.example.name
+  repo    = gitea_repository.example.name
   content = file("${path.module}/post-receive.sh")
 }
 ```

docs/resources/org.md

@@ -16,13 +16,13 @@ Organisations are a way to group repositories and abstract permission management
 ## Example Usage
 
 ```terraform
-resource "gitea_org" "test_org" {
-  name = "test-org"
+resource "gitea_org" "example" {
+  name = "org-example-org"
 }
 
-resource "gitea_repository" "org_repo" {
-  username = gitea_org.test_org.name
-  name = "org-test-repo"
+resource "gitea_repository" "example" {
+  username = gitea_org.example.name
+  name     = "org-example-repo"
 }
 ```
 

docs/resources/public_key.md

@@ -14,18 +14,17 @@ description: |-
 
 ```terraform
 resource "gitea_user" "test" {
-  username             = "test"
-  login_name           = "test"
+  username             = "public-key-test"
+  login_name           = "public-key-test"
   password             = "Geheim1!"
-  email                = "[email protected]"
+  email                = "public-key-[email protected]"
   must_change_password = false
 }
 
-
 resource "gitea_public_key" "test_user_key" {
-  title     = "test"
-  key       = file("${path.module}/id_ed25519.pub")
-  username  = gitea_user.test.username
+  title    = "public-key-test"
+  key      = file("${path.module}/id_ed25519.pub")
+  username = gitea_user.test.username
 }
 ```
 

docs/resources/repository.md

@@ -21,33 +21,52 @@ Repository migrations have some properties that are not available to regular rep
 ## Example Usage
 
 ```terraform
+resource "gitea_user" "example" {
+  username   = "repo_example_user"
+  login_name = "repo_example_user"
+  password   = "Geheim1!"
+  email      = "[email protected]"
+}
+
 resource "gitea_repository" "test" {
-  username     = "lerentis"
-  name         = "test"
+  username     = gitea_user.example.username
+  name         = "repository-test"
   private      = true
   issue_labels = "Default"
   license      = "MIT"
   gitignores   = "Go"
 }
 
 resource "gitea_repository" "mirror" {
-  username                     = "lerentis"
+  username                     = gitea_user.example.username
   name                         = "terraform-provider-gitea-mirror"
   description                  = "Mirror of Terraform Provider"
   mirror                       = true
   migration_clone_addresse     = "https://git.uploadfilter24.eu/lerentis/terraform-provider-gitea.git"
   migration_service            = "gitea"
   migration_service_auth_token = var.gitea_mirror_token
+
+  depends_on = [gitea_user.example]
 }
 
 resource "gitea_repository" "clone" {
-  username                     = "lerentis"
+  username                     = gitea_user.example.username
   name                         = "terraform-provider-gitea-clone"
   description                  = "Clone of Terraform Provider"
   mirror                       = false
   migration_clone_address      = "https://git.uploadfilter24.eu/lerentis/terraform-provider-gitea.git"
   migration_service            = "gitea"
   migration_service_auth_token = var.gitea_clone_token
+
+  depends_on = [gitea_user.example]
+}
+
+variable "gitea_mirror_token" {
+  default = "dummy-token"
+}
+
+variable "gitea_clone_token" {
+  default = "dummy-token"
 }
 ```
 

docs/resources/repository_actions_secret.md

@@ -0,0 +1,28 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "gitea_repository_actions_secret Resource - terraform-provider-gitea"
+subcategory: ""
+description: |-
+  
+---
+
+# gitea_repository_actions_secret (Resource)
+
+
+
+
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `repository` (String) Name of the repository.
+- `repository_owner` (String) Owner of the repository.
+- `secret_name` (String) Name of the secret.
+- `secret_value` (String, Sensitive) Value of the secret.
+
+### Read-Only
+
+- `created_at` (String) Date of 'actions_secret' creation.
+- `id` (String) The ID of this resource.

docs/resources/repository_actions_variable.md

@@ -0,0 +1,27 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "gitea_repository_actions_variable Resource - terraform-provider-gitea"
+subcategory: ""
+description: |-
+  
+---
+
+# gitea_repository_actions_variable (Resource)
+
+
+
+
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `repository` (String) Name of the repository.
+- `repository_owner` (String) Owner of the repository.
+- `value` (String) Value of the variable.
+- `variable_name` (String) Name of the variable.
+
+### Read-Only
+
+- `id` (String) The ID of this resource.

docs/resources/repository_key.md

@@ -16,30 +16,29 @@ Every key needs a unique name and unique key, i.e. no key can be added twice to
 ## Example Usage
 
 ```terraform
-terraform {
-  required_providers {
-    tls = {
-      source = "hashicorp/tls"
-      version = "4.0.4"
-    }
-  }
+resource "tls_private_key" "example" {
+  algorithm = "RSA"
+  rsa_bits  = 4096
 }
 
-resource "tls_private_key" "example" {
-  type = "RSA"
-  rsa_bits = 4096
+resource "gitea_user" "example" {
+  username   = "repo_key_example_user"
+  login_name = "repo_key_example_user"
+  password   = "Geheim1!"
+  email      = "[email protected]"
 }
 
 resource "gitea_repository" "example" {
-  name = "example"
-  private = true
+  name     = "example"
+  username = gitea_user.example.username
+  private  = true
 }
 
 resource "gitea_repository_key" "example" {
   repository = gitea_repository.example.id
-  title = "Example Deploy Key"
-  read_only = true
-  key = tls_private_key.example.public_key_openssh
+  title      = "Example Deploy Key"
+  read_only  = true
+  key        = tls_private_key.example.public_key_openssh
 }
 ```