Update docs for v17.0.0 release

CHANGELOG.md

@@ -1,3 +1,58 @@
+## 17.0.0 (2024-05-16)
+
+This release was tested against GitLab 17.0, 16.11, and 16.10 for both CE and EE
+
+KNOWN ISSUES:
+
+- `gitlab_current_user` returns an empty string for `public_email` ([#6305](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/issues/6305))
+
+BREAKING CHANGES:
+
+- resources/project_protected_environment: Removed support for `required_approval_count` field, use `required_approvals` in `approval_rules` or `deploy_access_level` instead ([!1940](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1940))
+- resources/group_protected_environment: Removed support for `required_approval_count` field, use `required_approvals` in `approval_rules` or `deploy_access_level` instead ([!1940](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1940))
+- resources/gitlab_group: Removed a version check related to `commit_committer_check` and `reject_unsigned_commits` that would prevent their use in versions prior to GitLab 16.4. If used with versions earlier than 16.4, these attributes will cause an error instead of being excluded. ([!1937](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1937))
+- resources/gitlab_group: Removed support for `emails_disabled`, use `emails_enabled` instead ([!1929](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1929))
+- resources/gitlab_project: Removed support for `emails_disabled`, use `emails_enabled` instead ([!1929](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1929))
+- resources/gitlab_pipeline_schedule: `ref` now requires the full ref instead of allowing the use of the short ref. If you previously used `main`, you now need to use `refs/heads/main` instead, for example ([!1923](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1923))
+- resources/gitlab_pipeline_trigger: `token` can no longer be imported. ([!1905](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1905))
+- resources/gitlab_pipeline_trigger: Updating the `project` attribute will now force the creation of a new pipeline trigger ([!1905](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1905))
+- data/gitlab_group(s): Removed support for `emails_disabled`, use `emails_enabled` instead ([!1929](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1929))
+- data/gitlab_project(s): Removed support for `emails_disabled`, use `emails_enabled` instead ([!1929](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1929))
+- data/gitlab_project(s): Removed support for `public`, use `visibility` instead ([!1929](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1929))
+- `master` is no longer a valid access level on any resource that supports the use of access levels. This impacts the resources listed below. ([!1903](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1903))
+  - gitlab_group_access_token
+  - gitlab_group_ldap_link
+  - gitlab_group_membership
+  - gitlab_group_share_group
+  - gitlab_project_access_token
+  - gitlab_project_membership
+  - gitlab_project_share_group
+
+IMPROVEMENTS:
+
+- **New Resource** resource/gitlab_integration_jenkins: Allows managing a project Jenkins integration ([!1919](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1919))
+- **New Resource** resource/gitlab_project_push_rules:  Allows managing the lifecycle of push rules on a project ([!1893](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1893))
+- **New Resource** resource/gitlab_project_job_token_scopes: This resource sets a strict list of project job token scopes, and removes any job token scopes not managed by the resource. This can be useful to explicitly deny job token scopes on a project. ([!1907](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1907))
+- resources/gitlab_pipeline_schedule_variable: Added support for the use of `variable_type` ([!1952](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1952))
+- resources/gitlab_group: Added support for the use of `commit_committer_name_check` to the `push_rules` block ([!1937](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1937))
+- resources/gitlab_project: Added support for the use of `commit_committer_name_check` to the `push_rules` block ([!1918](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1918))
+- resources/gitlab_instance_variable: Added support for the use of `description` ([!1950](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1950))
+- resources/gitlab_user_runner: Added example documentation for this resource to make it easier to consume ([!1928](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1928))
+- resources/gitlab_application_settings: Add support for `minimum_password_length` to the resource ([!1917](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1917))
+- resources/gitlab_personal_access_token: Updated the API used to read personal access token data, which improves performance of this resource in situations where many tokens are being maintained, and improves reliability of the resource in high concurrency situations ([!1908](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1908))
+- data/gitlab_instance_variable: Added support for `description` ([!1950](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1950))
+- provider: Added documentation that the use of Project Access Tokens or Group Access Tokens may not work with all resources ([!1928](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1928))
+
+BUG FIXES:
+
+- resources/gitlab_pipeline_schedule: Fixed a provider crash in situations where the scheduled pipeline fails to create ([!1899](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1899))
+- resources/gitlab_group: Fixed a provider error when attempting to create groups with `push_rules` on GitLab CE where `push_rules` are not supported ([!1891](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1891))
+- resources/gitlab_group_access_token: Fixed an issue with token rotation using `rotation_configuration` where tokens wouldn't rotate properly after `expires_at` was stored in state. Added additional debug logging for token rotation. ([!1953](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1953))
+- resources/gitlab_group_access_token: Fixed an issue with token rotation where manually managing expiration using `expires_at` would encounter an error after updating `expires_at` twice ([!1916](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1916))
+- resources/gitlab_project_access_token: Fixed an issue with token rotation using `rotation_configuration` where tokens wouldn't rotate properly after `expires_at` was stored in state. Added additional debug logging for token rotation. ([!1953](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1953))
+- resources/gitlab_project_access_token: Fixed an issue with token rotation where manually managing expiration using `expires_at` would encounter an error after updating `expires_at` twice ([!1916](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1916))
+- resources/gitlab_pipeline_trigger: Fixed a bug where applying TF with different users could corrupt the pipeline trigger `token` [!1905](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1905)
+
 ## 16.11.0 (2024-04-18)
 
 This release was tested against GitLab 16.9, 16.10, and 16.11 for both CE and EE

docs/data-sources/group_subgroups.md

@@ -59,7 +59,6 @@ Read-Only:
 - `created_at` (String)
 - `default_branch_protection` (Number)
 - `description` (String)
-- `emails_disabled` (Boolean)
 - `emails_enabled` (Boolean)
 - `file_template_project_id` (Number)
 - `full_name` (String)

docs/data-sources/instance_variable.md

@@ -30,6 +30,7 @@ data "gitlab_instance_variable" "foo" {
 
 ### Read-Only
 
+- `description` (String) The description of the variable. Maximum of 255 characters.
 - `id` (String) The ID of this resource.
 - `masked` (Boolean) If set to `true`, the value of the variable will be hidden in job logs. The value must meet the [masking requirements](https://docs.gitlab.com/ee/ci/variables/#masked-variables). Defaults to `false`.
 - `protected` (Boolean) If set to `true`, the variable will be passed only to pipelines running on protected branches and tags. Defaults to `false`.

docs/data-sources/instance_variables.md

@@ -32,6 +32,7 @@ data "gitlab_instance_variables" "vars" {}
 
 Read-Only:
 
+- `description` (String)
 - `key` (String)
 - `masked` (Boolean)
 - `protected` (Boolean)

docs/data-sources/project.md

@@ -55,7 +55,6 @@ data "gitlab_project" "example" {
 - `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.
 - `description` (String) A description of the project.
-- `emails_disabled` (Boolean, Deprecated) Disable email notifications.
 - `emails_enabled` (Boolean) Enable email notifications.
 - `empty_repo` (Boolean) Whether the project is empty.
 - `environments_access_level` (String) Set the environments access level. Valid values are `disabled`, `private`, `enabled`.
@@ -126,6 +125,7 @@ Read-Only:
 - `author_email_regex` (String)
 - `branch_name_regex` (String)
 - `commit_committer_check` (Boolean)
+- `commit_committer_name_check` (Boolean)
 - `commit_message_negative_regex` (String)
 - `commit_message_regex` (String)
 - `deny_delete_tag` (Boolean)

docs/data-sources/project_membership.md

@@ -4,7 +4,7 @@ page_title: "gitlab_project_membership Data Source - terraform-provider-gitlab"
 subcategory: ""
 description: |-
   The gitlab_project_membership data source allows to list and filter all members of a project specified by either its id or full path.
-  -> Note exactly one of projectid or fullpath must be provided.
+  -> Note exactly one of project_id or full_path must be provided.
   Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/members.html#list-all-members-of-a-group-or-project
 ---
 

docs/data-sources/projects.md

@@ -105,7 +105,6 @@ Read-Only:
 - `custom_attributes` (List of Map of String)
 - `default_branch` (String)
 - `description` (String)
-- `emails_disabled` (Boolean)
 - `emails_enabled` (Boolean)
 - `empty_repo` (Boolean)
 - `environments_access_level` (String)
@@ -150,7 +149,6 @@ Read-Only:
 - `path` (String)
 - `path_with_namespace` (String)
 - `permissions` (List of Object) (see [below for nested schema](#nestedobjatt--projects--permissions))
-- `public` (Boolean)
 - `public_builds` (Boolean)
 - `readme_url` (String)
 - `releases_access_level` (String)

docs/index.md

@@ -20,6 +20,10 @@ Use the navigation to the left to read about the valid data sources and resource
 This provider requires at least [Terraform 1.0](https://www.terraform.io/downloads.html).
 A minimum of Terraform 1.4.0 is recommended.
 
+-> Using a Project or Group access token may cause issues with some resources, as those token types don't 
+have full access to every API. This is also true when using a `CI_JOB_TOKEN`. Consider using a dedicated
+Personal Access Token or Service Account if you are experiencing permission errors when adding resources. 
+
 ## Example Usage
 
 ```terraform

docs/resources/application_settings.md

@@ -5,11 +5,11 @@ subcategory: ""
 description: |-
   The gitlab_application_settings resource allows to manage the GitLab application settings.
   ~> This is an experimental resource. By nature it doesn't properly fit into how Terraform resources are meant to work.
-     Feel free to join the discussion https://gitlab.com/gitlab-org/terraform-provider-gitlab/issues/957 if you have any
-     ideas or questions regarding this resource.
+  Feel free to join the discussion https://gitlab.com/gitlab-org/terraform-provider-gitlab/issues/957 if you have any
+  ideas or questions regarding this resource.
   ~> All gitlab_application_settings use the same ID gitlab.
   !> This resource does not implement any destroy logic, it's a no-op at this point.
-     It's also not possible to revert to the previous settings.
+  It's also not possible to revert to the previous settings.
   -> Requires at administrative privileges on GitLab.
   Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/settings.html
 ---
@@ -190,6 +190,7 @@ resource "gitlab_application_settings" "this" {
 - `max_personal_access_token_lifetime` (Number) Maximum allowable lifetime for access tokens in days.
 - `max_ssh_key_lifetime` (Number) Maximum allowable lifetime for SSH keys in days. Introduced in GitLab 14.6.
 - `metrics_method_call_threshold` (Number) A method call is only tracked when it takes longer than the given amount of milliseconds.
+- `minimum_password_length` (Number) Indicates whether passwords require a minimum length. Introduced in GitLab 15.1. Premium and Ultimate only.
 - `mirror_available` (Boolean) Allow repository mirroring to configured by project Maintainers. If disabled, only Administrators can configure repository mirroring.
 - `mirror_capacity_threshold` (Number) Minimum capacity to be available before scheduling more mirrors preemptively.
 - `mirror_max_capacity` (Number) Maximum number of mirrors that can be synchronizing at the same time.

docs/resources/branch_protection.md

@@ -5,12 +5,12 @@ subcategory: ""
 description: |-
   The gitlab_branch_protection resource allows to manage the lifecycle of a protected branch of a repository.
   ~> Branch Protection Behavior for the default branch
-     Depending on the GitLab instance, group or project setting the default branch of a project is created automatically by GitLab behind the scenes.
-     Due to some https://gitlab.com/gitlab-org/terraform-provider-gitlab/issues/792 limitations https://discuss.hashicorp.com/t/ignore-the-order-of-a-complex-typed-list/42242 in the Terraform Provider SDK and the GitLab API,
-     when creating a new project and trying to manage the branch protection setting for its default branch the gitlab_branch_protection resource will
-     automatically take ownership of the default branch without an explicit import by unprotecting and properly protecting it again.
-     Having multiple gitlab_branch_protection resources for the same project and default branch will result in them overriding each other - make sure to only have a single one.
-     This behavior might change in the future.
+  Depending on the GitLab instance, group or project setting the default branch of a project is created automatically by GitLab behind the scenes.
+  Due to some https://gitlab.com/gitlab-org/terraform-provider-gitlab/issues/792 limitations https://discuss.hashicorp.com/t/ignore-the-order-of-a-complex-typed-list/42242 in the Terraform Provider SDK and the GitLab API,
+  when creating a new project and trying to manage the branch protection setting for its default branch the gitlab_branch_protection resource will
+  automatically take ownership of the default branch without an explicit import by unprotecting and properly protecting it again.
+  Having multiple gitlab_branch_protection resources for the same project and default branch will result in them overriding each other - make sure to only have a single one.
+  This behavior might change in the future.
   ~> The allowed_to_push, allowed_to_merge, allowed_to_unprotect, unprotect_access_level and code_owner_approval_required attributes require a GitLab Enterprise instance.
   Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/protected_branches.html
 ---

docs/resources/cluster_agent.md

@@ -5,9 +5,9 @@ subcategory: ""
 description: |-
   The gitlab_cluster_agent resource allows to manage the lifecycle of a GitLab Agent for Kubernetes.
   -> Note that this resource only registers the agent, but doesn't configure it.
-     The configuration needs to be manually added as described in
-     the docs https://docs.gitlab.com/ee/user/clusters/agent/install/index.html#create-an-agent-configuration-file.
-     However, a gitlab_repository_file resource may be used to achieve that.
+  The configuration needs to be manually added as described in
+  the docs https://docs.gitlab.com/ee/user/clusters/agent/install/index.html#create-an-agent-configuration-file.
+  However, a gitlab_repository_file resource may be used to achieve that.
   -> Requires at least maintainer permissions on the project.
   -> Requires at least GitLab 14.10
   Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/cluster_agents.html

docs/resources/group.md

@@ -62,7 +62,6 @@ resource "gitlab_group" "example-two" {
 - `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) See https://docs.gitlab.com/ee/api/groups.html#options-for-default_branch_protection. Valid values are: `0`, `1`, `2`, `3`, `4`.
 - `description` (String) The group's description.
-- `emails_disabled` (Boolean, Deprecated) Disable email notifications.
 - `emails_enabled` (Boolean) Enable email notifications.
 - `extra_shared_runners_minutes_limit` (Number) Can be set by administrators only. Additional CI/CD minutes for this group.
 - `ip_restriction_ranges` (List of String) A list of IP addresses or subnet masks to restrict group access. Will be concatenated together into a comma separated string. Only allowed on top level groups.
@@ -100,6 +99,7 @@ Optional:
 - `author_email_regex` (String) All commit author emails must match this regex, e.g. `@my-company.com$`.
 - `branch_name_regex` (String) All branch names must match this regex, e.g. `(feature|hotfix)\/*`.
 - `commit_committer_check` (Boolean) Only commits pushed using verified emails are allowed.  **Note** This attribute is only supported in GitLab versions >= 16.4.
+- `commit_committer_name_check` (Boolean) Users can only push commits to this repository if the commit author name is consistent with their GitLab account name.
 - `commit_message_negative_regex` (String) No commit message is allowed to match this regex, for example `ssh\:\/\/`.
 - `commit_message_regex` (String) All commit messages must match this regex, e.g. `Fixed \d+\..*`.
 - `deny_delete_tag` (Boolean) Deny deleting a tag.

docs/resources/group_access_token.md

@@ -52,7 +52,7 @@ resource "gitlab_group_variable" "example" {
 
 ### Optional
 
-- `access_level` (String) The access level for the group access token. Valid values are: `no one`, `minimal`, `guest`, `reporter`, `developer`, `maintainer`, `owner`, `master`. Default is `maintainer`.
+- `access_level` (String) The access level for the group access token. Valid values are: `no one`, `minimal`, `guest`, `reporter`, `developer`, `maintainer`, `owner`. Default is `maintainer`.
 - `expires_at` (String) When the token will expire, YYYY-MM-DD format.
 - `rotation_configuration` (Attributes) The configuration for when to rotate a token automatically. Will not rotate a token until `terraform apply` is run. (see [below for nested schema](#nestedatt--rotation_configuration))
 

docs/resources/group_ldap_link.md

@@ -34,11 +34,11 @@ resource "gitlab_group_ldap_link" "test" {
 
 ### Optional
 
-- `access_level` (String, Deprecated) Minimum access level for members of the LDAP group. Valid values are: `no one`, `minimal`, `guest`, `reporter`, `developer`, `maintainer`, `owner`, `master`
+- `access_level` (String, Deprecated) Minimum access level for members of the LDAP group. Valid values are: `no one`, `minimal`, `guest`, `reporter`, `developer`, `maintainer`, `owner`
 - `cn` (String) The CN of the LDAP group to link with. Required if `filter` is not provided.
 - `filter` (String) The LDAP filter for the group. Required if `cn` is not provided. Requires GitLab Premium or above.
 - `force` (Boolean) If true, then delete and replace an existing LDAP link if one exists. Will also remove an LDAP link if the parent group is not found.
-- `group_access` (String) Minimum access level for members of the LDAP group. Valid values are: `no one`, `minimal`, `guest`, `reporter`, `developer`, `maintainer`, `owner`, `master`
+- `group_access` (String) Minimum access level for members of the LDAP group. Valid values are: `no one`, `minimal`, `guest`, `reporter`, `developer`, `maintainer`, `owner`
 
 ### Read-Only