Update docs for v17.2.0 release

gitlab-terraform-provider-bot · gitlab-terraform-provider-bot · commit 6ff98a7fca93 · 2024-07-19T00:30:45.000Z
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,24 @@
 
+## 17.2.0 (2024-07-18)
+
+This release was tested against GitLab 17.2, 17.1, and 17.0 for both CE and EE
+
+### BREAKING CHANGES (1 change)
+Note: As a security related change, this breaking change is allowed outside a major release. If a non-sensitive token is required for migration purposes users can use the `nonsensitive()` TF function.
+
+- resource/gitlab_cluster_agent_token: [Mark GitLab cluster agent token as sensitive](gitlab-org/terraform-provider-gitlab@1eec1065723f6393a3e5deb45356a47ec27b575e) by @CarbonCollins ([merge request](gitlab-org/terraform-provider-gitlab!2032)) 
+
+### IMPROVEMENTS (1 change)
+
+- **New Resource** resource/gitlab_project_security_policy_attachment: [Add new resource for associating security policy projects to a project](gitlab-org/terraform-provider-gitlab@3fc5f6c8a9d74f8b034af84a73fb9dcb6d323179) by @PatrickRice ([merge request](gitlab-org/terraform-provider-gitlab!2009))
+- resource/gitlab_personal_access_token: [Migrate `gitlab_personal_access_token` from SDK to TF Plugin Framework](gitlab-org/terraform-provider-gitlab@24489118da1ce464994cdfcedecbe804edf65490) by @theipster ([merge request](gitlab-org/terraform-provider-gitlab!2005)) 
+- 
+
+### BUG FIXES (4 changes)
+
+- resource/gitlab_deploy_key: [Fix deploy key documentation reference to point to the correct resource for enabling a pre-existing deploy key](gitlab-org/terraform-provider-gitlab@f8718e66a5608c521009d091761b5577a055e904) by @blrz ([merge request](gitlab-org/terraform-provider-gitlab!2024)) 
+- resource/gitlab_user_runner: [Fix an issue with gitlab_user_runner causing inconsistent TF plans](gitlab-org/terraform-provider-gitlab@a5448baf255134f0d0bff5fe16803ee4cf35ce61) by @PatrickRice ([merge request](gitlab-org/terraform-provider-gitlab!2020)) 
+
 ## 17.1.0 (2024-06-20)
 
 This release was tested against GitLab 17.1, 17.0, and 16.11 for both CE and EE
diff --git a/docs/resources/cluster_agent_token.md b/docs/resources/cluster_agent_token.md
@@ -84,7 +84,7 @@ resource "helm_release" "gitlab_agent" {
 - `id` (String) The ID of this resource.
 - `last_used_at` (String) The ISO8601 datetime when the token was last used.
 - `status` (String) The status of the token. Valid values are `active`, `revoked`.
-- `token` (String) The secret token for the agent. The `token` is not available in imported resources.
+- `token` (String, Sensitive) The secret token for the agent. The `token` is not available in imported resources.
 - `token_id` (Number) The ID of the token.
 
 ## Import
diff --git a/docs/resources/deploy_key.md b/docs/resources/deploy_key.md
@@ -4,15 +4,15 @@ page_title: "gitlab_deploy_key Resource - terraform-provider-gitlab"
 subcategory: ""
 description: |-
   The gitlab_deploy_key resource allows to manage the lifecycle of a deploy key.
-  -> To enable an already existing deploy key for another project use the gitlab_project_deploy_key resource.
+  -> To enable an already existing deploy key for another project use the gitlab_deploy_key_enable resource.
   Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/deploy_keys.html
 ---
 
 # gitlab_deploy_key (Resource)
 
 The `gitlab_deploy_key` resource allows to manage the lifecycle of a deploy key.
 
--> To enable an already existing deploy key for another project use the `gitlab_project_deploy_key` resource.
+-> To enable an already existing deploy key for another project use the `gitlab_deploy_key_enable` resource.
 
 **Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/deploy_keys.html)
 
diff --git a/docs/resources/personal_access_token.md b/docs/resources/personal_access_token.md
@@ -3,18 +3,27 @@
 page_title: "gitlab_personal_access_token Resource - terraform-provider-gitlab"
 subcategory: ""
 description: |-
-  The gitlab_personal_access_token resource allows to manage the lifecycle of a personal access token for a specified user.
+  The gitlab_personal_access_token resource allows to manage the lifecycle of a personal access token.
   -> This resource requires administration privileges.
-  Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/personal_access_tokens.html
+  ~> Use of the timestamp() function with expires_at will cause the resource to be re-created with every apply, it's recommended to use plantimestamp() or a static value instead.
+  ~> Observability scopes are in beta and may not work on all instances. See more details in the documentation https://docs.gitlab.com/ee/operations/tracing.html
+  ~> Due to Automatic reuse detection https://docs.gitlab.com/ee/api/personal_access_tokens.html#automatic-reuse-detection it's possible that a new Personal Access Token will immediately be revoked. Check if an old process using the old token is running if this happens.
+  Upstream API: GitLab API docs https://docs.gitlab.com/ee/api/personal_access_tokens.html
 ---
 
 # gitlab_personal_access_token (Resource)
 
-The `gitlab_personal_access_token` resource allows to manage the lifecycle of a personal access token for a specified user.
+The `gitlab_personal_access_token` resource allows to manage the lifecycle of a personal access token.
 
 -> This resource requires administration privileges.
 
-**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/personal_access_tokens.html)
+~> Use of the `timestamp()` function with expires_at will cause the resource to be re-created with every apply, it's recommended to use `plantimestamp()` or a static value instead.
+
+~> Observability scopes are in beta and may not work on all instances. See more details in [the documentation](https://docs.gitlab.com/ee/operations/tracing.html)
+
+~> Due to [Automatic reuse detection](https://docs.gitlab.com/ee/api/personal_access_tokens.html#automatic-reuse-detection) it's possible that a new Personal Access Token will immediately be revoked. Check if an old process using the old token is running if this happens.
+
+**Upstream API**: [GitLab API docs](https://docs.gitlab.com/ee/api/personal_access_tokens.html)
 
 ## Example Usage
 
@@ -40,20 +49,20 @@ resource "gitlab_project_variable" "example" {
 ### Required
 
 - `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`, `create_runner`, `manage_runner`.
-- `user_id` (Number) The id of the user.
+- `scopes` (Set of String) The scopes of the personal access token. valid values are: `api`, `read_user`, `read_api`, `read_repository`, `write_repository`, `read_registry`, `write_registry`, `sudo`, `admin_mode`, `create_runner`, `manage_runner`, `ai_features`, `k8s_proxy`, `read_service_ping`
+- `user_id` (Number) The ID of the user.
 
 ### Optional
 
-- `expires_at` (String) The token expires at midnight UTC on that date. The date must be in the format YYYY-MM-DD.
+- `expires_at` (String) When the token will expire, YYYY-MM-DD format.
 
 ### Read-Only
 
 - `active` (Boolean) True if the token is active.
 - `created_at` (String) Time the token has been created, RFC3339 format.
-- `id` (String) The ID of this resource.
+- `id` (String) The ID of the personal access token.
 - `revoked` (Boolean) True if the token is revoked.
-- `token` (String, Sensitive) The personal access token. This is only populated when creating a new personal access token. This attribute is not available for imported resources.
+- `token` (String, Sensitive) The token of the personal access token. **Note**: the token is not available for imported resources.
 
 ## Import
 
diff --git a/docs/resources/project_security_policy_attachment.md b/docs/resources/project_security_policy_attachment.md
@@ -0,0 +1,89 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "gitlab_project_security_policy_attachment Resource - terraform-provider-gitlab"
+subcategory: ""
+description: |-
+  The gitlab_project_security_policy_attachment resource allows to attach a security policy project to a project.
+  Upstream API: GitLab GraphQL API docs https://docs.gitlab.com/ee/api/graphql/reference/index.html#mutationsecuritypolicyprojectassign
+---
+
+# gitlab_project_security_policy_attachment (Resource)
+
+The `gitlab_project_security_policy_attachment` resource allows to attach a security policy project to a project.
+
+**Upstream API**: [GitLab GraphQL API docs](https://docs.gitlab.com/ee/api/graphql/reference/index.html#mutationsecuritypolicyprojectassign)
+
+## Example Usage
+
+```terraform
+# This resource can be used to attach a security policy to a pre-existing project
+resource "gitlab_project_security_policy_attachment" "foo" {
+  project        = 1234
+  policy_project = 4567
+}
+
+
+# Or you can use Terraform to create a new project, add a policy to that project,
+# then attach that policy project to other projects.
+resource "gitlab_project" "my-policy-project" {
+  name = "security-policy-project"
+}
+
+resource "gitlab_repository_file" "policy-yml" {
+  project   = gitlab_project.my-policy-project.id
+  file_path = ".gitlab/security-policies/my-policy.yml"
+  branch    = "master"
+  encoding  = "text"
+  content   = <<-EOT
+---
+approval_policy:
+- name: test
+description: test
+enabled: true
+rules:
+- type: any_merge_request
+    branch_type: protected
+    commits: any
+approval_settings:
+    block_branch_modification: true
+    prevent_pushing_and_force_pushing: true
+    prevent_approval_by_author: true
+    prevent_approval_by_commit_author: true
+    remove_approvals_with_new_commit: true
+    require_password_to_approve: false
+fallback_behavior:
+    fail: closed
+actions:
+- type: send_bot_message
+    enabled: true
+EOT
+}
+
+resource "gitlab_project_security_policy" "my-policy" {
+  project        = 1234
+  policy_project = gitlab_project.my-policy-project.id
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `policy_project` (String) The ID or Full Path of the security policy project.
+- `project` (String) The ID or Full Path of the project which will have the security policy project assigned to it.
+
+### Read-Only
+
+- `id` (String) The ID of this Terraform resource. In the format of `<project>:<policy_project>`.
+- `policy_project_graphql_id` (String) The GraphQL ID of the security policy project.
+- `project_graphql_id` (String) The GraphQL ID of the project to which the security policty project will be attached.
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# GitLab project security policy attachments can be imported using an id made up of `project:policy_project_id` where the policy project ID is the project ID of the policy project, e.g.
+terraform import gitlab_project_security_policy_attachment.foo 1:2
+```
