started with documentation

README.md

@@ -7,3 +7,67 @@ Terraform Gitea Provider
 ## History
 
 This is a fork of https://gitea.com/gitea/terraform-provider-gitea. Many thanks for the foundation of this provider  
+
+## Usage
+
+This is not a 1.0 release, so usage is subject to change!
+
+```terraform
+terraform {
+  required_providers {
+    gitea = {
+      source = "Lerentis/gitea"
+      version = "0.3.0"
+    }
+  }
+}
+
+provider "gitea" {
+  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 
+  
+  # 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 
+}
+
+resource "gitea_repository" "test" {
+  username     = "lerentis"
+  name         = "test"
+  private      = true
+  issue_labels = "Default"
+  license      = "MIT"
+  gitignores   = "Go"
+}
+
+resource "gitea_repository" "mirror" {
+  username                     = "lerentis"
+  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
+}
+
+resource "gitea_org" "test_org" {
+  name = "test-org"
+}
+
+resource "gitea_repository" "org_repo" {
+  username = gitea_org.test_org.name
+  name = "org-test-repo"
+}
+
+```
+
+## Contributing
+
+This repo is a mirror of [uploadfilter24.eu](https://git.uploadfilter24.eu/lerentis/terraform-provider-gitea), where i mostly develop. PRs will be manually merged on the gitea instance as keeping these two repositories in sync can be very error prune.

docs/index.md

@@ -10,7 +10,34 @@ description: |-
 
 
 
+## Example Usage
 
+```terraform
+terraform {
+  required_providers {
+    gitea = {
+      source = "Lerentis/gitea"
+      version = "0.3.0"
+    }
+  }
+}
+
+provider "gitea" {
+  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 
+  
+  # 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 
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/resources/org.md

@@ -3,30 +3,44 @@
 page_title: "gitea_org Resource - terraform-provider-gitea"
 subcategory: ""
 description: |-
-  Handling Ogranisation resources
+  gitea_org manages a gitea organisation.
+  Organisations are a way to group repositories and abstract permission management in a gitea instance.
 ---
 
 # gitea_org (Resource)
 
-Handling Ogranisation resources
+`gitea_org` manages a gitea organisation.
 
+Organisations are a way to group repositories and abstract permission management in a gitea instance.
 
+## Example Usage
+
+```terraform
+resource "gitea_org" "test_org" {
+  name = "test-org"
+}
+
+resource "gitea_repository" "org_repo" {
+  username = gitea_org.test_org.name
+  name = "org-test-repo"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `name` (String)
+- `name` (String) The name of the organisation without spaces.
 
 ### Optional
 
-- `description` (String)
+- `description` (String) A description of this organisation.
-- `full_name` (String)
+- `full_name` (String) The display name of the organisation. Defaults to the value of `name`.
 - `location` (String)
 - `repo_admin_change_team_access` (Boolean)
-- `visibility` (String)
+- `visibility` (String) Flag is this organisation should be publicly visible or not.
-- `website` (String)
+- `website` (String) A link to a website with more information about this organisation.
 
 ### Read-Only
 

docs/resources/repository.md

@@ -3,22 +3,51 @@
 page_title: "gitea_repository Resource - terraform-provider-gitea"
 subcategory: ""
 description: |-
-  Handling Repository resources
+  gitea_repository manages a gitea repository.
+  Per default this repository will be initializiled with the provided configuration (gitignore, License etc.).
+  If the username property is set to a organisation name, the provider will try to look if this organisation exists and create the repository under the organisation scope.
+  Repository migrations have some properties that are not available to regular repositories. These are all prefixed with migration_.
 ---
 
 # gitea_repository (Resource)
 
-Handling Repository resources
+`gitea_repository` manages a gitea repository.
 
+Per default this repository will be initializiled with the provided configuration (gitignore, License etc.).
+If the `username` property is set to a organisation name, the provider will try to look if this organisation exists and create the repository under the organisation scope.
 
+Repository migrations have some properties that are not available to regular repositories. These are all prefixed with `migration_`.
+
+## Example Usage
+
+```terraform
+resource "gitea_repository" "test" {
+  username     = "lerentis"
+  name         = "test"
+  private      = true
+  issue_labels = "Default"
+  license      = "MIT"
+  gitignores   = "Go"
+}
+
+resource "gitea_repository" "mirror" {
+  username                     = "lerentis"
+  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
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `name` (String)
+- `name` (String) The Name of the repository
-- `username` (String)
+- `username` (String) The Owner of the repository
 
 ### Optional
 
@@ -28,18 +57,21 @@ Handling Repository resources
 - `allow_rebase_explicit` (Boolean)
 - `allow_squash_merge` (Boolean)
 - `archived` (Boolean)
-- `auto_init` (Boolean)
+- `auto_init` (Boolean) Flag if the repository should be initiated with the configured values
 - `autodetect_manual_merge` (Boolean)
-- `default_branch` (String)
+- `default_branch` (String) The default branch of the repository. Defaults to `main`
-- `description` (String)
+- `description` (String) The description of the repository.
-- `gitignores` (String)
+- `gitignores` (String) A specific gitignore that should be commited to the repositoryon creation if `auto_init` is set to `true`
-- `has_issues` (Boolean)
+Need to exist in the gitea instance
-- `has_projects` (Boolean)
+- `has_issues` (Boolean) A flag if the repository should have issue management enabled or not.
-- `has_pull_requests` (Boolean)
+- `has_projects` (Boolean) A flag if the repository should have the native project management enabled or not.
-- `has_wiki` (Boolean)
+- `has_pull_requests` (Boolean) A flag if the repository should acceppt pull requests or not.
+- `has_wiki` (Boolean) A flag if the repository should have the native wiki enabled or not.
 - `ignore_whitespace_conflicts` (Boolean)
-- `issue_labels` (String)
+- `issue_labels` (String) The Issue Label configuration to be used in this repository.
-- `license` (String)
+Need to exist in the gitea instance
+- `license` (String) The license under which the source code of this repository should be.
+Need to exist in the gitea instance
 - `migration_clone_addresse` (String)
 - `migration_issue_labels` (Boolean)
 - `migration_lfs` (Boolean)
@@ -52,10 +84,10 @@ Handling Repository resources
 - `migration_service_auth_token` (String, Sensitive)
 - `migration_service_auth_username` (String)
 - `mirror` (Boolean)
-- `private` (Boolean)
+- `private` (Boolean) Flag if the repository should be private or not.
 - `readme` (String)
 - `repo_template` (Boolean)
-- `website` (String)
+- `website` (String) A link to a website with more information.
 
 ### Read-Only
 

examples/provider.tf

@@ -1,13 +0,0 @@
-terraform {
-  required_providers {
-    gitea = {
-      source = "terraform.local/lerentis/gitea"
-      version = "0.3.0"
-    }
-  }
-}
-
-provider "gitea" {
-  base_url = var.gitea_url
-  token    = var.gitea_token
-}

examples/provider/provider.tf

@@ -0,0 +1,24 @@
+terraform {
+  required_providers {
+    gitea = {
+      source = "Lerentis/gitea"
+      version = "0.3.0"
+    }
+  }
+}
+
+provider "gitea" {
+  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 
+  
+  # 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 
+}

examples/resources/gitea_org/resource.tf

@@ -0,0 +1,8 @@
+resource "gitea_org" "test_org" {
+  name = "test-org"
+}
+
+resource "gitea_repository" "org_repo" {
+  username = gitea_org.test_org.name
+  name = "org-test-repo"
+}

examples/resources/gitea_repository/resource.tf

@@ -0,0 +1,18 @@
+resource "gitea_repository" "test" {
+  username     = "lerentis"
+  name         = "test"
+  private      = true
+  issue_labels = "Default"
+  license      = "MIT"
+  gitignores   = "Go"
+}
+
+resource "gitea_repository" "mirror" {
+  username                     = "lerentis"
+  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
+}

gitea/resource_gitea_organisation.go

@@ -139,24 +139,28 @@ func resourceGiteaOrg() *schema.Resource {
 		},
 		Schema: map[string]*schema.Schema{
 			"name": {
-				Type:     schema.TypeString,
+				Type:        schema.TypeString,
-				Required: true,
+				Required:    true,
-				ForceNew: true,
+				ForceNew:    true,
+				Description: "The name of the organisation without spaces.",
 			},
 			"full_name": {
-				Type:     schema.TypeString,
+				Type:        schema.TypeString,
-				Required: false,
+				Required:    false,
-				Optional: true,
+				Optional:    true,
+				Description: "The display name of the organisation. Defaults to the value of `name`.",
 			},
 			"description": {
-				Type:     schema.TypeString,
+				Type:        schema.TypeString,
-				Required: false,
+				Required:    false,
-				Optional: true,
+				Optional:    true,
+				Description: "A description of this organisation.",
 			},
 			"website": {
-				Type:     schema.TypeString,
+				Type:        schema.TypeString,
-				Required: false,
+				Required:    false,
-				Optional: true,
+				Optional:    true,
+				Description: "A link to a website with more information about this organisation.",
 			},
 			"location": {
 				Type:     schema.TypeString,
@@ -175,12 +179,14 @@ func resourceGiteaOrg() *schema.Resource {
 				Computed: true,
 			},
 			"visibility": {
-				Type:     schema.TypeString,
+				Type:        schema.TypeString,
-				Required: false,
+				Required:    false,
-				Optional: true,
+				Optional:    true,
-				Default:  "public",
+				Default:     "public",
+				Description: "Flag is this organisation should be publicly visible or not.",
 			},
 		},
-		Description: "Handling Ogranisation resources",
+		Description: "`gitea_org` manages a gitea organisation.\n\n" +
+			"Organisations are a way to group repositories and abstract permission management in a gitea instance.",
 	}
 }

gitea/resource_gitea_repository.go

@@ -259,20 +259,23 @@ func resourceGiteaRepository() *schema.Resource {
 		},
 		Schema: map[string]*schema.Schema{
 			"username": {
-				Type:     schema.TypeString,
+				Type:        schema.TypeString,
-				Required: true,
+				Required:    true,
-				ForceNew: true,
+				ForceNew:    true,
+				Description: "The Owner of the repository",
 			},
 			"name": {
-				Type:     schema.TypeString,
+				Type:        schema.TypeString,
-				Required: true,
+				Required:    true,
-				ForceNew: true,
+				ForceNew:    true,
+				Description: "The Name of the repository",
 			},
 			"auto_init": {
-				Type:     schema.TypeBool,
+				Type:        schema.TypeBool,
-				Required: false,
+				Required:    false,
-				Optional: true,
+				Optional:    true,
-				Default:  true,
+				Default:     true,
+				Description: "Flag if the repository should be initiated with the configured values",
 			},
 			"repo_template": {
 				Type:     schema.TypeBool,
@@ -285,18 +288,25 @@ func resourceGiteaRepository() *schema.Resource {
 				Required: false,
 				Optional: true,
 				Default:  "Default",
+				Description: "The Issue Label configuration to be used in this repository.\n" +
+					"Need to exist in the gitea instance",
 			},
 			"gitignores": {
 				Type:     schema.TypeString,
 				Required: false,
 				Optional: true,
 				Default:  "",
+				Description: "A specific gitignore that should be commited to the repository" +
+					"on creation if `auto_init` is set to `true`\n" +
+					"Need to exist in the gitea instance",
 			},
 			"license": {
 				Type:     schema.TypeString,
 				Required: false,
 				Optional: true,
 				Default:  "",
+				Description: "The license under which the source code of this repository should be.\n" +
+					"Need to exist in the gitea instance",
 			},
 			"readme": {
 				Type:     schema.TypeString,
@@ -305,22 +315,25 @@ func resourceGiteaRepository() *schema.Resource {
 				Default:  "",
 			},
 			"description": {
-				Type:     schema.TypeString,
+				Type:        schema.TypeString,
-				Required: false,
+				Required:    false,
-				Optional: true,
+				Optional:    true,
-				Default:  "",
+				Default:     "",
+				Description: "The description of the repository.",
 			},
 			"private": {
-				Type:     schema.TypeBool,
+				Type:        schema.TypeBool,
-				Required: false,
+				Required:    false,
-				Optional: true,
+				Optional:    true,
-				Default:  true,
+				Default:     true,
+				Description: "Flag if the repository should be private or not.",
 			},
 			"default_branch": {
-				Type:     schema.TypeString,
+				Type:        schema.TypeString,
-				Required: false,
+				Required:    false,
-				Optional: true,
+				Optional:    true,
-				Default:  "main",
+				Default:     "main",
+				Description: "The default branch of the repository. Defaults to `main`",
 			},
 			"created": {
 				Type:     schema.TypeString,
@@ -343,34 +356,39 @@ func resourceGiteaRepository() *schema.Resource {
 				Computed: true,
 			},
 			"website": {
-				Type:     schema.TypeString,
+				Type:        schema.TypeString,
-				Required: false,
+				Required:    false,
-				Optional: true,
+				Optional:    true,
-				Default:  "",
+				Default:     "",
+				Description: "A link to a website with more information.",
 			},
 			"has_issues": {
-				Type:     schema.TypeBool,
+				Type:        schema.TypeBool,
-				Required: false,
+				Required:    false,
-				Optional: true,
+				Optional:    true,
-				Default:  true,
+				Default:     true,
+				Description: "A flag if the repository should have issue management enabled or not.",
 			},
 			"has_wiki": {
-				Type:     schema.TypeBool,
+				Type:        schema.TypeBool,
-				Required: false,
+				Required:    false,
-				Optional: true,
+				Optional:    true,
-				Default:  true,
+				Default:     true,
+				Description: "A flag if the repository should have the native wiki enabled or not.",
 			},
 			"has_pull_requests": {
-				Type:     schema.TypeBool,
+				Type:        schema.TypeBool,
-				Required: false,
+				Required:    false,
-				Optional: true,
+				Optional:    true,
-				Default:  true,
+				Default:     true,
+				Description: "A flag if the repository should acceppt pull requests or not.",
 			},
 			"has_projects": {
-				Type:     schema.TypeBool,
+				Type:        schema.TypeBool,
-				Required: false,
+				Required:    false,
-				Optional: true,
+				Optional:    true,
-				Default:  true,
+				Default:     true,
+				Description: "A flag if the repository should have the native project management enabled or not.",
 			},
 			"ignore_whitespace_conflicts": {
 				Type:     schema.TypeBool,
@@ -496,6 +514,10 @@ func resourceGiteaRepository() *schema.Resource {
 				Default:  "",
 			},
 		},
-		Description: "Handling Repository resources",
+		Description: "`gitea_repository` manages a gitea repository.\n\n" +
+			"Per default this repository will be initializiled with the provided configuration (gitignore, License etc.).\n" +
+			"If the `username` property is set to a organisation name, the provider will try to look if this organisation exists " +
+			"and create the repository under the organisation scope.\n\n" +
+			"Repository migrations have some properties that are not available to regular repositories. These are all prefixed with `migration_`.",
 	}
 }