Update docs for v15.7.0 release

gitlab-terraform-provider-bot · gitlab-terraform-provider-bot · commit d27c7be75483 · 2022-12-22T22:59:45.000Z
diff --git a/docs/data-sources/metadata.md b/docs/data-sources/metadata.md
@@ -0,0 +1,42 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "gitlab_metadata Data Source - terraform-provider-gitlab"
+subcategory: ""
+description: |-
+  The gitlab_metadata data source retrieves the metadata of the GitLab instance.
+  Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/metadata.html
+---
+
+# gitlab_metadata (Data Source)
+
+The `gitlab_metadata` data source retrieves the metadata of the GitLab instance.
+
+**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/metadata.html)
+
+## Example Usage
+
+```terraform
+data "gitlab_metadata" "this" {}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Read-Only
+
+- `enterprise` (Boolean) If the GitLab instance is an enterprise instance or not. Supported for GitLab 15.6 onwards.
+- `id` (String) The id of the data source. It will always be `1`
+- `kas` (Attributes) Metadata about the GitLab agent server for Kubernetes (KAS). (see [below for nested schema](#nestedatt--kas))
+- `revision` (String) Revision of the GitLab instance.
+- `version` (String) Version of the GitLab instance.
+
+<a id="nestedatt--kas"></a>
+### Nested Schema for `kas`
+
+Read-Only:
+
+- `enabled` (Boolean) Indicates whether KAS is enabled.
+- `external_url` (String) URL used by the agents to communicate with KAS. It’s null if kas.enabled is false.
+- `version` (String) Version of KAS. It’s null if kas.enabled is false.
+
+
diff --git a/docs/data-sources/project.md b/docs/data-sources/project.md
@@ -47,6 +47,7 @@ data "gitlab_project" "example" {
 - `build_timeout` (Number) The maximum amount of time, in seconds, that a job can run.
 - `builds_access_level` (String) Set the builds access level. Valid values are `disabled`, `private`, `enabled`.
 - `ci_config_path` (String) CI config file path for the project.
+- `ci_separated_caches` (Boolean) Use separate caches for protected branches.
 - `container_expiration_policy` (List of Object) Set the image cleanup policy for this project. **Note**: this field is sometimes named `container_expiration_policy_attributes` in the GitLab Upstream API. (see [below for nested schema](#nestedatt--container_expiration_policy))
 - `container_registry_access_level` (String) Set visibility of container registry, for this project. Valid values are `disabled`, `private`, `enabled`.
 - `default_branch` (String) The default branch for the project.
@@ -76,6 +77,7 @@ data "gitlab_project" "example" {
 - `request_access_enabled` (Boolean) Allow users to request member access.
 - `requirements_access_level` (String) Set the requirements access level. Valid values are `disabled`, `private`, `enabled`.
 - `resolve_outdated_diff_discussions` (Boolean) Automatically resolve merge request diffs discussions on lines changed with a push.
+- `restrict_user_defined_variables` (Boolean) Allow only users with the Maintainer role to pass user-defined variables when triggering a pipeline.
 - `runners_token` (String) Registration token to use during runner setup.
 - `security_and_compliance_access_level` (String) Set the security and compliance access level. Valid values are `disabled`, `private`, `enabled`.
 - `snippets_access_level` (String) Set the snippets access level. Valid values are `disabled`, `private`, `enabled`.
diff --git a/docs/data-sources/projects.md b/docs/data-sources/projects.md
@@ -148,6 +148,7 @@ Read-Only:
 - `request_access_enabled` (Boolean)
 - `requirements_access_level` (String)
 - `resolve_outdated_diff_discussions` (Boolean)
+- `restrict_user_defined_variables` (Boolean)
 - `runners_token` (String)
 - `security_and_compliance_access_level` (String)
 - `shared_runners_enabled` (Boolean)
diff --git a/docs/guides/version-15.7-upgrade.md b/docs/guides/version-15.7-upgrade.md
@@ -0,0 +1,67 @@
+---
+page_title: "Terraform GitLab Provider Version 15.7 Upgrade Guide"
+---
+
+# Upgrade to Terraform GitLab Provider Version 15.7
+
+Because the GitLab Provider has moved to [GitLab.com](https://gitlab.com/gitlab-org/terraform-provider-gitlab),
+the release cadence and versioning has been
+[aligned](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/issues/1331) with the GitLab
+[monthly self-managed release cadence](https://about.gitlab.com/handbook/engineering/releases/)
+starting with 15.7 (22nd Dec 2022).
+
+The version bump from [`3.20.0`](https://registry.terraform.io/providers/gitlabhq/gitlab/3.20.0) to
+[`v15.7.0`](https://registry.terraform.io/providers/gitlabhq/gitlab/15.7.0) introduced a few breaking changes,
+which are described below.
+
+
+## Terraform version 1.0
+
+The GitLab Provider upgraded to
+[Terraform Protocol v6](https://developer.hashicorp.com/terraform/plugin/how-terraform-works#protocol-version-6),
+which **requires at least Terraform 1.0**.
+
+## Provider token is now sensitive
+
+The `token` Provider argument is now marked as
+[`sensitive`](https://developer.hashicorp.com/terraform/tutorials/configuration-language/sensitive-variables).
+This affects current Provider configurations, which read the `token` value from another non-sensitive Terraform value,
+like an output attribute or variable.
+
+Because the `variable "gitlab_token"` declaration doesn't mark the variable as `sensitive`,
+code like the following will break:
+
+```hcl
+variable "gitlab_token" {
+  type = string
+}
+
+provider "gitlab" {
+  token = var.gitlab_token
+}
+```
+There are two ways to resolve this issue:
+
+- If you have control over the token value, mark it as
+[sensitive](https://developer.hashicorp.com/terraform/language/values/variables#suppressing-values-in-cli-output):
+
+  ```hcl
+  variable "gitlab_token" {
+    type      = string
+    sensitive = true
+  }
+
+  provider "gitlab" {
+    token = var.gitlab_token
+  }
+  ```
+
+- If you don't have control over the token value, use the
+[`sensitive()`](https://developer.hashicorp.com/terraform/language/functions/sensitive) function to create
+a *sensitive* copy of the value to use:
+
+  ```hcl
+  provider "gitlab" {
+    token = sensitive(some_other_module.gitlab_token)
+  }
+  ```
diff --git a/docs/index.md b/docs/index.md
@@ -69,15 +69,12 @@ resource "gitlab_project" "sample_group_project" {
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
-### Required
-
-- `token` (String) The OAuth2 Token, Project, Group, Personal Access Token or CI Job Token used to connect to GitLab. The OAuth method is used in this provider for authentication (using Bearer authorization token). See https://docs.gitlab.com/ee/api/#authentication for details. It may be sourced from the `GITLAB_TOKEN` environment variable.
-
 ### Optional
 
 - `base_url` (String) This is the target GitLab base API endpoint. Providing a value is a requirement when working with GitLab CE or GitLab Enterprise e.g. `https://my.gitlab.server/api/v4/`. It is optional to provide this value and it can also be sourced from the `GITLAB_BASE_URL` environment variable. The value must end with a slash.
 - `cacert_file` (String) This is a file containing the ca cert to verify the gitlab instance. This is available for use when working with GitLab CE or Gitlab Enterprise with a locally-issued or self-signed certificate chain.
 - `client_cert` (String) File path to client certificate when GitLab instance is behind company proxy. File must contain PEM encoded data.
 - `client_key` (String) File path to client key when GitLab instance is behind company proxy. File must contain PEM encoded data. Required when `client_cert` is set.
-- `early_auth_check` (Boolean) (Experimental) By default the provider does a dummy request to get the current user in order to verify that the provider configuration is correct and the GitLab API is reachable. Turn it off, to skip this check. This may be useful if the GitLab instance does not yet exist and is created within the same terraform module. This is an experimental feature and may change in the future. Please make sure to always keep backups of your state.
+- `early_auth_check` (Boolean) (Experimental) By default the provider does a dummy request to get the current user in order to verify that the provider configuration is correct and the GitLab API is reachable. Set this to `false` to skip this check. This may be useful if the GitLab instance does not yet exist and is created within the same terraform module. This is an experimental feature and may change in the future. Please make sure to always keep backups of your state.
 - `insecure` (Boolean) When set to true this disables SSL verification of the connection to the GitLab instance.
+- `token` (String, Sensitive) The OAuth2 Token, Project, Group, Personal Access Token or CI Job Token used to connect to GitLab. The OAuth method is used in this provider for authentication (using Bearer authorization token). See https://docs.gitlab.com/ee/api/#authentication for details. It may be sourced from the `GITLAB_TOKEN` environment variable.
diff --git a/docs/resources/group.md b/docs/resources/group.md
@@ -44,6 +44,8 @@ resource "gitlab_project" "example" {
 ### Optional
 
 - `auto_devops_enabled` (Boolean) Defaults to false. Default to Auto DevOps pipeline for all projects within this group.
+- `avatar` (String) A local path to the avatar image to upload. **Note**: not available for imported resources.
+- `avatar_hash` (String) The hash of the avatar image. Use `filesha256("path/to/avatar.png")` whenever possible. **Note**: this is used to trigger an update of the avatar. If it's not given, but an avatar is given, the avatar will be updated each time.
 - `default_branch_protection` (Number) Defaults to 2. See https://docs.gitlab.com/ee/api/groups.html#options-for-default_branch_protection
 - `description` (String) The description of the group.
 - `emails_disabled` (Boolean) Defaults to false. Disable email notifications.
@@ -64,6 +66,7 @@ resource "gitlab_project" "example" {
 
 ### Read-Only
 
+- `avatar_url` (String) The URL of the avatar image.
 - `full_name` (String) The full name of the group.
 - `full_path` (String) The full path of the group.
 - `id` (String) The ID of this resource.
diff --git a/docs/resources/group_project_file_template.md b/docs/resources/group_project_file_template.md
@@ -42,8 +42,8 @@ resource "gitlab_project" "bar" {
 }
 
 resource "gitlab_group_project_file_template" "template_link" {
-  group_id = gitlab_group.foo.id
-  project  = gitlab_project.bar.id
+  group_id                 = gitlab_group.foo.id
+  file_template_project_id = gitlab_project.bar.id
 }
 ```
 
diff --git a/docs/resources/project.md b/docs/resources/project.md
@@ -84,20 +84,24 @@ resource "gitlab_project" "peters_repo" {
 - `auto_devops_deploy_strategy` (String) Auto Deploy strategy. Valid values are `continuous`, `manual`, `timed_incremental`.
 - `auto_devops_enabled` (Boolean) Enable Auto DevOps for this project.
 - `autoclose_referenced_issues` (Boolean) Set whether auto-closing referenced issues on default branch.
+- `avatar` (String) A local path to the avatar image to upload. **Note**: not available for imported resources.
+- `avatar_hash` (String) The hash of the avatar image. Use `filesha256("path/to/avatar.png")` whenever possible. **Note**: this is used to trigger an update of the avatar. If it's not given, but an avatar is given, the avatar will be updated each time.
 - `build_coverage_regex` (String, Deprecated) Test coverage parsing for the project. This is deprecated feature in GitLab 15.0.
 - `build_git_strategy` (String) The Git strategy. Defaults to fetch.
 - `build_timeout` (Number) The maximum amount of time, in seconds, that a job can run.
 - `builds_access_level` (String) Set the builds access level. Valid values are `disabled`, `private`, `enabled`.
 - `ci_config_path` (String) Custom Path to CI config file.
 - `ci_default_git_depth` (Number) Default number of revisions for shallow cloning.
 - `ci_forward_deployment_enabled` (Boolean) When a new deployment job starts, skip older deployment jobs that are still pending.
+- `ci_separated_caches` (Boolean) Use separate caches for protected branches.
 - `container_expiration_policy` (Block List, Max: 1) Set the image cleanup policy for this project. **Note**: this field is sometimes named `container_expiration_policy_attributes` in the GitLab Upstream API. (see [below for nested schema](#nestedblock--container_expiration_policy))
 - `container_registry_access_level` (String) Set visibility of container registry, for this project. Valid values are `disabled`, `private`, `enabled`.
-- `container_registry_enabled` (Boolean) Enable container registry for the project.
+- `container_registry_enabled` (Boolean, Deprecated) Enable container registry for the project.
 - `default_branch` (String) The default branch for the project.
 - `description` (String) A description of the project.
 - `emails_disabled` (Boolean) Disable email notifications.
 - `external_authorization_classification_label` (String) The classification label for the project.
+- `forked_from_project_id` (Number) The id of the project to fork. During create the project is forked and during an update the fork relation is changed.
 - `forking_access_level` (String) Set the forking access level. Valid values are `disabled`, `private`, `enabled`.
 - `group_with_project_templates_id` (Number) For group-level custom templates, specifies ID of group from which all the custom project templates are sourced. Leave empty for instance-level templates. Requires use_custom_template to be true (enterprise edition).
 - `import_url` (String) Git URL to a repository to be imported.
@@ -134,6 +138,7 @@ resource "gitlab_project" "peters_repo" {
 - `request_access_enabled` (Boolean) Allow users to request member access.
 - `requirements_access_level` (String) Set the requirements access level. Valid values are `disabled`, `private`, `enabled`.
 - `resolve_outdated_diff_discussions` (Boolean) Automatically resolve merge request diffs discussions on lines changed with a push.
+- `restrict_user_defined_variables` (Boolean) Allow only users with the Maintainer role to pass user-defined variables when triggering a pipeline.
 - `security_and_compliance_access_level` (String) Set the security and compliance access level. Valid values are `disabled`, `private`, `enabled`.
 - `shared_runners_enabled` (Boolean) Enable shared runners for this project.
 - `skip_wait_for_default_branch_protection` (Boolean) If `true`, the default behavior to wait for the default branch protection to be created is skipped.
@@ -156,6 +161,7 @@ This attribute is only used during resource creation, thus changes are suppresse
 
 ### Read-Only
 
+- `avatar_url` (String) The URL of the avatar image.
 - `http_url_to_repo` (String) URL that can be provided to `git clone` to clone the
 - `id` (String) The ID of this resource.
 - `path_with_namespace` (String) The path of the repository with namespace.
diff --git a/docs/resources/repository_file.md b/docs/resources/repository_file.md
@@ -58,6 +58,18 @@ resource "gitlab_repository_file" "readme" {
   author_name    = "Terraform"
   commit_message = "feature: add readme file"
 }
+
+resource "gitlab_repository_file" "readme_for_dogs" {
+  project        = gitlab_project.this.id
+  file_path      = "readme.txt"
+  branch         = "main"
+  content        = "Bark goes the dog"
+  author_email   = "terraform@example.com"
+  author_name    = "Terraform"
+  commit_message = "feature: update readme file"
+  // file will be overwritten if it already exists and added to state
+  overwrite_on_create = true
+}
 ```
 
 <!-- schema generated by tfplugindocs -->
@@ -76,6 +88,7 @@ resource "gitlab_repository_file" "readme" {
 - `author_email` (String) Email of the commit author.
 - `author_name` (String) Name of the commit author.
 - `execute_filemode` (Boolean) Enables or disables the execute flag on the file. **Note**: requires GitLab 14.10 or newer.
+- `overwrite_on_create` (Boolean) Enable overwriting existing files, defaults to `false`. This attribute is only used during `create` and must be use carefully. We suggest to use `imports` whenever possible and limit the use of this attribute for when the project was imported on the same `apply`. This attribute is not supported during a resource import.
 - `start_branch` (String) Name of the branch to start the new commit from.
 - `timeouts` (Block, Optional) (see [below for nested schema](#nestedblock--timeouts))
 

Original file line number	Diff line number	Diff line change
`@@ -42,8 +42,8 @@ resource "gitlab_project" "bar" {`
`42`	`42`	`}`
`43`	`43`
`44`	`44`	`resource "gitlab_group_project_file_template" "template_link" {`
`45`		`- group_id = gitlab_group.foo.id`
`46`		`- project = gitlab_project.bar.id`
	`45`	`+ group_id = gitlab_group.foo.id`
	`46`	`+ file_template_project_id = gitlab_project.bar.id`
`47`	`47`	`}`
`48`	`48`	```
`49`	`49`