Update docs for v16.4.0 release

Author: gitlab-terraform-provider-bot

CHANGELOG.md

@@ -1,3 +1,29 @@
+## 16.4.0 (2023-09-22)
+
+This release was tested against GitLab 16.2, 16.3, and 16.4 for both CE and EE
+
+BREAKING CHANGES:
+
+This breaking change was made early for security reasons. If a configuration relies on the value being non-sensitive, 
+users can use the [`nonsensitive()`](https://developer.hashicorp.com/terraform/language/functions/nonsensitive) function
+in Terraform.
+
+- resource/gitlab_user_runner: `token` is now marked as sensitive ([!1688](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1688))
+
+IMPROVEMENTS:
+
+- resource/gitlab_project_mirror: Updated documentation to include a warning about `keep_divergent_refs` default value ([!1691](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1691))
+- resource/gitlab_project_protected_environment: Add support for `approval_rules` ([!1679](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1679))
+- resource/gitlab_group_access_token: Add support for the `create_runner` scope ([!1675](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1675))
+- resource/gitlab_personal_access_token: Add support for the `create_runner` scope ([!1675](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1675))
+- resource/gitlab_project_access_token: Add support for the `create_runner` scope ([!1675](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1675))
+
+BUG FIXES:
+
+- resource/gitlab_branch: No longer returns an error when the branch is missing during a destroy ([!1690](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1690))
+- datasource/gitlab_cluster_agents: Fixed an issue where `agent_id` was always `0` ([!1677](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1677))
+- datasource/gitlab_group_subgroups: Fixed an issue where the data source returned a maximum of 20 subgroups ([!1689](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/1689))
+
 ## 16.3.0 (2023-08-22)
 
 This release was tested against GitLab 16.0, 16.1, and 16.2 for both CE and EE

docs/resources/group_access_token.md

@@ -43,7 +43,7 @@ resource "gitlab_group_variable" "example" {
 - `expires_at` (String) The token expires at midnight UTC on that date. The date must be in the format YYYY-MM-DD.
 - `group` (String) The ID or path of the group to add the group access token to.
 - `name` (String) The name of the group access token.
-- `scopes` (Set of String) The scope for the group access token. It determines the actions which can be performed when authenticating with this token. Valid values are: `api`, `read_api`, `read_registry`, `write_registry`, `read_repository`, `write_repository`.
+- `scopes` (Set of String) The scope for the group access token. It determines the actions which can be performed when authenticating with this token. Valid values are: `api`, `read_api`, `read_registry`, `write_registry`, `read_repository`, `write_repository`, `create_runner`.
 
 ### Optional
 

docs/resources/integration_mattermost.md

@@ -0,0 +1,77 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "gitlab_integration_mattermost Resource - terraform-provider-gitlab"
+subcategory: ""
+description: |-
+  The gitlab_integration_mattermost resource allows to manage the lifecycle of a project integration with Mattermost.
+  Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/integrations.html#mattermost-notifications
+---
+
+# gitlab_integration_mattermost (Resource)
+
+The `gitlab_integration_mattermost` resource allows to manage the lifecycle of a project integration with Mattermost.
+
+**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/integrations.html#mattermost-notifications)
+
+## Example Usage
+
+```terraform
+resource "gitlab_project" "awesome_project" {
+  name             = "awesome_project"
+  description      = "My awesome project."
+  visibility_level = "public"
+}
+
+resource "gitlab_integration_mattermost" "mattermost" {
+  project      = gitlab_project.awesome_project.id
+  webhook      = "https://webhook.com"
+  username     = "myuser"
+  push_events  = true
+  push_channel = "push_chan"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `project` (String) ID of the project you want to activate integration on.
+- `webhook` (String) Webhook URL (Example, https://mattermost.yourdomain.com/hooks/...). This value cannot be imported.
+
+### Optional
+
+- `branches_to_be_notified` (String) Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected".
+- `confidential_issue_channel` (String) The name of the channel to receive confidential issue events notifications.
+- `confidential_issues_events` (Boolean) Enable notifications for confidential issues events.
+- `confidential_note_channel` (String) The name of the channel to receive confidential note events notifications.
+- `confidential_note_events` (Boolean) Enable notifications for confidential note events.
+- `issue_channel` (String) The name of the channel to receive issue events notifications.
+- `issues_events` (Boolean) Enable notifications for issues events.
+- `merge_request_channel` (String) The name of the channel to receive merge request events notifications.
+- `merge_requests_events` (Boolean) Enable notifications for merge requests events.
+- `note_channel` (String) The name of the channel to receive note events notifications.
+- `note_events` (Boolean) Enable notifications for note events.
+- `notify_only_broken_pipelines` (Boolean) Send notifications for broken pipelines.
+- `pipeline_channel` (String) The name of the channel to receive pipeline events notifications.
+- `pipeline_events` (Boolean) Enable notifications for pipeline events.
+- `push_channel` (String) The name of the channel to receive push events notifications.
+- `push_events` (Boolean) Enable notifications for push events.
+- `tag_push_channel` (String) The name of the channel to receive tag push events notifications.
+- `tag_push_events` (Boolean) Enable notifications for tag push events.
+- `username` (String) Username to use.
+- `wiki_page_channel` (String) The name of the channel to receive wiki page events notifications.
+- `wiki_page_events` (Boolean) Enable notifications for wiki page events.
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# You can import a gitlab_integration_mattermost.mattermost state using the project ID, e.g.
+terraform import gitlab_integration_mattermost.mattermost 1
+```

docs/resources/integration_slack.md

@@ -74,5 +74,5 @@ Import is supported using the following syntax:
 
 ```shell
 # You can import a gitlab_integration_slack.slack state using the project ID, e.g.
-terraform import gitlab_integration_slack.slack.email 1
+terraform import gitlab_integration_slack.slack 1
 ```

docs/resources/personal_access_token.md

@@ -41,7 +41,7 @@ resource "gitlab_project_variable" "example" {
 
 - `expires_at` (String) The token expires at midnight UTC on that date. The date must be in the format YYYY-MM-DD.
 - `name` (String) The name of the personal access token.
-- `scopes` (Set of String) The scope for the personal access token. It determines the actions which can be performed when authenticating with this token. Valid values are: `api`, `read_user`, `read_api`, `read_repository`, `write_repository`, `read_registry`, `write_registry`, `sudo`, `admin_mode`.
+- `scopes` (Set of String) The scope for the personal access token. It determines the actions which can be performed when authenticating with this token. Valid values are: `api`, `read_user`, `read_api`, `read_repository`, `write_repository`, `read_registry`, `write_registry`, `sudo`, `admin_mode`, `create_runner`.
 - `user_id` (Number) The id of the user.
 
 ### Read-Only

docs/resources/project_access_token.md

@@ -40,7 +40,7 @@ resource "gitlab_project_variable" "example" {
 - `expires_at` (String) Time the token will expire it, YYYY-MM-DD format.
 - `name` (String) A name to describe the project access token.
 - `project` (String) The id of the project to add the project access token to.
-- `scopes` (Set of String) Valid values: `api`, `read_api`, `read_repository`, `write_repository`, `read_registry`, `write_registry`.
+- `scopes` (Set of String) The scope for the project access token. It determines the actions which can be performed when authenticating with this token. Valid values are: `api`, `read_api`, `read_registry`, `write_registry`, `read_repository`, `write_repository`, `create_runner`.
 
 ### Optional
 

docs/resources/project_mirror.md

@@ -6,6 +6,9 @@ description: |-
   The gitlab_project_mirror resource allows to manage the lifecycle of a project mirror.
   This is for pushing changes to a remote repository. Pull Mirroring can be configured using a combination of the
   importurl, mirror, and mirrortriggerbuilds properties on the gitlabproject resource.
+  -> Warning By default, the provider sets the keep_divergent_refs argument to True.
+     If you manually set keep_divergent_refs to False, GitLab mirroring removes branches in the target that aren't in the source.
+     This action can result in unexpected branch deletions.
   -> Destroy Behavior GitLab 14.10 introduced an API endpoint to delete a project mirror.
      Therefore, for GitLab 14.10 and newer the project mirror will be destroyed when the resource is destroyed.
      For older versions, the mirror will be disabled and the resource will be destroyed.
@@ -19,6 +22,10 @@ The `gitlab_project_mirror` resource allows to manage the lifecycle of a project
 This is for *pushing* changes to a remote repository. *Pull Mirroring* can be configured using a combination of the
 import_url, mirror, and mirror_trigger_builds properties on the gitlab_project resource.
 
+-> **Warning** By default, the provider sets the `keep_divergent_refs` argument to `True`.
+   If you manually set `keep_divergent_refs` to `False`, GitLab mirroring removes branches in the target that aren't in the source.
+   This action can result in unexpected branch deletions.
+
 -> **Destroy Behavior** GitLab 14.10 introduced an API endpoint to delete a project mirror.
    Therefore, for GitLab 14.10 and newer the project mirror will be destroyed when the resource is destroyed.
    For older versions, the mirror will be disabled and the resource will be destroyed.

docs/resources/project_protected_environment.md

@@ -33,7 +33,7 @@ resource "gitlab_project_environment" "this" {
   external_url = "www.example.com"
 }
 
-# Example with access level
+# Example with deployment access level
 resource "gitlab_project_protected_environment" "example_with_access_level" {
   project                 = gitlab_project_environment.this.project
   required_approval_count = 1
@@ -44,7 +44,7 @@ resource "gitlab_project_protected_environment" "example_with_access_level" {
   }
 }
 
-# Example with group
+# Example with group-based deployment level
 resource "gitlab_project_protected_environment" "example_with_group" {
   project     = gitlab_project_environment.this.project
   environment = gitlab_project_environment.this.name
@@ -54,7 +54,7 @@ resource "gitlab_project_protected_environment" "example_with_group" {
   }
 }
 
-# Example with user
+# Example with user-based deployment level
 resource "gitlab_project_protected_environment" "example_with_user" {
   project     = gitlab_project_environment.this.project
   environment = gitlab_project_environment.this.name
@@ -64,7 +64,7 @@ resource "gitlab_project_protected_environment" "example_with_user" {
   }
 }
 
-# Example with multiple access levels
+# Example with multiple deployment access levels
 resource "gitlab_project_protected_environment" "example_with_multiple" {
   project                 = gitlab_project_environment.this.project
   required_approval_count = 2
@@ -81,6 +81,46 @@ resource "gitlab_project_protected_environment" "example_with_multiple" {
   deploy_access_levels {
     user_id = 789
   }
+}
+
+# Example with access-level based approval rules
+resource "gitlab_project_protected_environment" "example_with_multiple" {
+  project                 = gitlab_project_environment.this.project
+  required_approval_count = 2
+  environment             = gitlab_project_environment.this.name
+
+  deploy_access_levels {
+    access_level = "developer"
+  }
+
+  approval_rules = [
+    {
+      access_level = "developer"
+    }
+  ]
+}
+
+# Example with multiple approval rules, using access level, user, and group
+resource "gitlab_project_protected_environment" "example_with_multiple" {
+  project                 = gitlab_project_environment.this.project
+  required_approval_count = 2
+  environment             = gitlab_project_environment.this.name
+
+  deploy_access_levels {
+    access_level = "developer"
+  }
+
+  approval_rules = [
+    {
+      user_id = 789
+    },
+    {
+      access_level = "developer"
+    },
+    {
+      group_id = 456
+    }
+  ]
 }
 ```
 
@@ -94,13 +134,30 @@ resource "gitlab_project_protected_environment" "example_with_multiple" {
 
 ### Optional
 
+- `approval_rules` (Attributes List) Array of approval rules to deploy, with each described by a hash. (see [below for nested schema](#nestedatt--approval_rules))
 - `deploy_access_levels` (Block Set) Array of access levels allowed to deploy, with each described by a hash. (see [below for nested schema](#nestedblock--deploy_access_levels))
 - `required_approval_count` (Number) The number of approvals required to deploy to this environment.
 
 ### Read-Only
 
 - `id` (String) The ID of this Terraform resource. In the format of `<project>:<environment-name>`.
 
+<a id="nestedatt--approval_rules"></a>
+### Nested Schema for `approval_rules`
+
+Optional:
+
+- `access_level` (String) Levels of access allowed to approve a deployment to this protected environment. Valid values are `developer`, `maintainer`.
+- `group_id` (Number) The ID of the group allowed to approve a deployment to this protected environment. The project must be shared with the group. This is mutually exclusive with user_id.
+- `required_approvals` (Number) The number of approval required to allow deployment to this protected environment. This is mutually exclusive with user_id.
+- `user_id` (Number) The ID of the user allowed to approve a deployment to this protected environment. The user must be a member of the project. This is mutually exclusive with group_id and required_approvals.
+
+Read-Only:
+
+- `access_level_description` (String) Readable description of level of access.
+- `id` (Number) The unique ID of the Approval Rules object.
+
+
 <a id="nestedblock--deploy_access_levels"></a>
 ### Nested Schema for `deploy_access_levels`
 
@@ -113,6 +170,7 @@ Optional:
 Read-Only:
 
 - `access_level_description` (String) Readable description of level of access.
+- `id` (Number) The unique ID of the Deploy Access Level object.
 
 ## Import
 

docs/resources/user_runner.md

@@ -37,4 +37,4 @@ The `gitlab_user_runner` resource allows creating a GitLab runner using the new
 ### Read-Only
 
 - `id` (String) The ID of the gitlab runner.
-- `token` (String) The authentication token to use when setting up a new runner with this configuration. This value cannot be imported.
+- `token` (String, Sensitive) The authentication token to use when setting up a new runner with this configuration. This value cannot be imported.