Update docs for v18.3.0 release

Author: gitlab-terraform-provider-bot

CHANGELOG.md

@@ -1,3 +1,29 @@
+## 18.3.0 (2025-08-22)
+
+### FEATURES (3 changes)
+
+- [Add new `gitlab_group_deploy_token` and `gitlab_project_deploy_token` resources. The existing generic `gitlab_deploy_token` resource has now been deprecated.](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/commit/888655dc0fe8b5a2733efbf06465164055afbe1c) by @mness ([merge request](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/2604)) 
+- [Add new `gitlab_group_saml_links` datasource](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/commit/e17475001ccb12a5bb0588411e74092f7c2f006f) by @heidi.berry ([merge request](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/2584))
+- [Support client-go config file for provider authentication. See more information here: https://gitlab.com/gitlab-org/api/client-go#use-the-config-package-experimental](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/commit/95a83237e7b2a1cb34149591d61a742f1d8ef179) by @timofurrer ([merge request](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/2592)) 
+
+### IMPROVEMENTS (6 changes)
+
+- resource/gitlab_project_level_notifications:  [Update to handle unknown value validation](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/commit/1bbebb2c0fd8f09f555a88d968c621fed6d662c9) by @PatrickRice ([merge request](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/2600)) 
+- resource/gitlab_group:  [Add support for `administrator` to `project_creation_level`](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/commit/2813a1a504a3f7bae3cced0cdedf1016f87ee291) by @aldo.salas1 ([merge request](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/2601)) 
+- resource/gitlab_group_security_policy_attachments: [This resource now checks permissions prior to adding the policy, and fails with a informative error if permissions are missing](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/commit/ce294bfe8a1d1980aeb1179c0b908e2bffc4a75e) by @PatrickRice ([merge request](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/2593)) 
+- resource/gitlab_project_security_policy_attachments: [This resource now checks permissions prior to adding the policy, and fails with a informative error if permissions are missing](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/commit/ce294bfe8a1d1980aeb1179c0b908e2bffc4a75e) by @PatrickRice ([merge request](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/2593)) 
+- resource/gitlab_deploy_token: [Add support for previously missing scope options](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/commit/888655dc0fe8b5a2733efbf06465164055afbe1c) by @mness ([merge request](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/2604)) 
+- resource/gitlab_instance_service_account: [Allow instance service accounts to be created without username and/or name](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/commit/642a9beb08e1248867ac3e0098aa765f65119bdb) by @heidi.berry ([merge request](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/2585)) 
+
+### BUG FIXES (6 changes)
+
+- resource/gitlab_global_level_notifications:  [Update to handle unknown value validation](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/commit/d36f740539b2a54490a50cf3bd1a03cab7981cad) by @PatrickRice ([merge request](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/2595)) 
+- resource/gitlab_project_level_notifications:  [Update to handle unknown value validation](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/commit/1bbebb2c0fd8f09f555a88d968c621fed6d662c9) by @PatrickRice ([merge request](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/2600)) 
+- resource/gitlab_project_protected_environment:  [Fix error in protected environment using unknown deploy attributes](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/commit/ec63e4f688c9cf5a9d1bd6e7ac2999440580dcf1) by @PatrickRice ([merge request](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/2594))
+- resource/gitlab_project_integration_github: [Fix a provider panic that occurs when importing a non-existent integration](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/commit/068405a8b0762ca680bed8943d32763bdafe19dc) by @heidi.berry ([merge request](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/2599))
+- resource/gitlab_group_dependency_proxy: [Fixed a bug where importing using an `import` block caused an immediate replace](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/commit/7be6298efafe222e23523554bd660f3a5a43d37a) by @PatrickRice ([merge request](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/2607)) 
+- resource/gitlab_group: [Fixed an issue with `permanently_remove_on_delete` that occurred when deleting groups on GitLab versions later than 18.0](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/commit/1a09f11f064069a9e19d26bdf592c5ea608af5b7) by @heidi.berry ([merge request](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/merge_requests/2598)) 
+
 ## 18.2.0 (2025-07-17)
 
 ### FEATURES (2 changes)

docs/data-sources/cluster_agents.md

@@ -3,13 +3,13 @@
 page_title: "gitlab_cluster_agents Data Source - terraform-provider-gitlab"
 subcategory: ""
 description: |-
-  The gitlab_cluster_agents data source allows details of GitLab Agents for Kubernetes in a project.
+  The gitlab_cluster_agents data source retrieves details of GitLab Agents for Kubernetes in a project.
   Upstream API: GitLab REST API docs https://docs.gitlab.com/api/cluster_agents/
 ---
 
 # gitlab_cluster_agents (Data Source)
 
-The `gitlab_cluster_agents` data source allows details of GitLab Agents for Kubernetes in a project.
+The `gitlab_cluster_agents` data source retrieves details of GitLab Agents for Kubernetes in a project.
 
 **Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/api/cluster_agents/)
 
@@ -26,20 +26,20 @@ data "gitlab_cluster_agents" "agents" {
 
 ### Required
 
-- `project` (String) The ID or full path of the project owned by the authenticated user.
+- `project` (String) ID or full path of the project maintained by the authenticated user.
 
 ### Read-Only
 
-- `cluster_agents` (List of Object) List of the registered agents. (see [below for nested schema](#nestedatt--cluster_agents))
-- `id` (String) The ID of this resource.
+- `cluster_agents` (Attributes List) List of the registered agents. (see [below for nested schema](#nestedatt--cluster_agents))
+- `id` (String) The ID of this data source. In the format <project>
 
 <a id="nestedatt--cluster_agents"></a>
 ### Nested Schema for `cluster_agents`
 
 Read-Only:
 
-- `agent_id` (Number)
-- `created_at` (String)
-- `created_by_user_id` (Number)
-- `name` (String)
-- `project` (String)
+- `agent_id` (Number) The ID of the agent.
+- `created_at` (String) The ISO8601 datetime when the agent was created.
+- `created_by_user_id` (Number) The ID of the user who created the agent.
+- `name` (String) The Name of the agent.
+- `project` (String) ID or full path of the project maintained by the authenticated user.

docs/data-sources/group_saml_links.md

@@ -0,0 +1,47 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "gitlab_group_saml_links Data Source - terraform-provider-gitlab"
+subcategory: ""
+description: |-
+  The gitlab_group_saml_links data source retrieves all SAML links for a specified group.
+  Upstream API: GitLab REST API docs https://docs.gitlab.com/api/saml/#saml-group-links
+---
+
+# gitlab_group_saml_links (Data Source)
+
+The `gitlab_group_saml_links` data source retrieves all SAML links for a specified group.
+	
+**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/api/saml/#saml-group-links)
+
+## Example Usage
+
+```terraform
+data "gitlab_group" "example" {
+  id = "foo/bar/baz"
+}
+
+data "gitlab_group_saml_links" "example" {
+  group = data.gitlab_group.example.id
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `group` (String) The name or id of the group.
+
+### Read-Only
+
+- `id` (String) The ID of this Terraform resource. In the format <group-id>
+- `saml_links` (Attributes List) The list of group SAML links returned by the search (see [below for nested schema](#nestedatt--saml_links))
+
+<a id="nestedatt--saml_links"></a>
+### Nested Schema for `saml_links`
+
+Read-Only:
+
+- `access_level` (String) The base access level for members of the SAML group.
+- `member_role_id` (Number) Member Role ID (custom role for members of the SAML group.
+- `name` (String) Name of the SAML group.

docs/data-sources/instance_variable.md

@@ -3,13 +3,13 @@
 page_title: "gitlab_instance_variable Data Source - terraform-provider-gitlab"
 subcategory: ""
 description: |-
-  The gitlab_instance_variable data source allows to retrieve details about an instance-level CI/CD variable.
+  The gitlab_instance_variable data source retrieves details about an instance-level CI/CD variable.
   Upstream API: GitLab REST API docs https://docs.gitlab.com/api/instance_level_ci_variables/
 ---
 
 # gitlab_instance_variable (Data Source)
 
-The `gitlab_instance_variable` data source allows to retrieve details about an instance-level CI/CD variable.
+The `gitlab_instance_variable` data source retrieves details about an instance-level CI/CD variable.
 
 **Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/api/instance_level_ci_variables/)
 
@@ -31,9 +31,9 @@ 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/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`.
-- `raw` (Boolean) Whether the variable is treated as a raw string. Default: false. When true, variables in the value are not expanded.
+- `id` (String) The ID of this datasource. In the format `<key>`.
+- `masked` (Boolean) If set to `true`, the value of the variable will be hidden in job logs.
+- `protected` (Boolean) If set to `true`, the variable will be passed only to pipelines running on protected branches and tags.
+- `raw` (Boolean) If set to `true`, the variable will be treated as a raw string.
 - `value` (String) The value of the variable.
-- `variable_type` (String) The type of a variable. Valid values are: `env_var`, `file`. Default is `env_var`.
+- `variable_type` (String) The type of the variable, either `env_var` or `file`.

docs/data-sources/instance_variables.md

@@ -3,13 +3,13 @@
 page_title: "gitlab_instance_variables Data Source - terraform-provider-gitlab"
 subcategory: ""
 description: |-
-  The gitlab_instance_variables data source allows to retrieve all instance-level CI/CD variables.
+  The gitlab_instance_variables data source retrieves all instance-level CI/CD variables.
   Upstream API: GitLab REST API docs https://docs.gitlab.com/api/instance_level_ci_variables/
 ---
 
 # gitlab_instance_variables (Data Source)
 
-The `gitlab_instance_variables` data source allows to retrieve all instance-level CI/CD variables.
+The `gitlab_instance_variables` data source retrieves all instance-level CI/CD variables.
 
 **Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/api/instance_level_ci_variables/)
 
@@ -24,18 +24,18 @@ data "gitlab_instance_variables" "vars" {}
 
 ### Read-Only
 
-- `id` (String) The ID of this resource.
-- `variables` (List of Object) The list of variables returned by the search (see [below for nested schema](#nestedatt--variables))
+- `id` (String) The ID of this datasource. In the hardcoded format `instance_variables`.
+- `variables` (Attributes List) The list of variables returned by the search. (see [below for nested schema](#nestedatt--variables))
 
 <a id="nestedatt--variables"></a>
 ### Nested Schema for `variables`
 
 Read-Only:
 
-- `description` (String)
-- `key` (String)
-- `masked` (Boolean)
-- `protected` (Boolean)
-- `raw` (Boolean)
-- `value` (String)
-- `variable_type` (String)
+- `description` (String) The description of the variable. Maximum of 255 characters.
+- `key` (String) The name of the variable.
+- `masked` (Boolean) If set to `true`, the value of the variable will be hidden in job logs.
+- `protected` (Boolean) If set to `true`, the variable will be passed only to pipelines running on protected branches and tags.
+- `raw` (Boolean) If set to `true`, the variable will be treated as a raw string.
+- `value` (String) The value of the variable.
+- `variable_type` (String) The type of the variable, either `env_var` or `file`.

docs/data-sources/project_variable.md

@@ -35,18 +35,18 @@ data "gitlab_project_variable" "bar" {
 ### Required
 
 - `key` (String) The name of the variable.
-- `project` (String) The name or id of the project.
+- `project` (String) The name or path of the project.
 
 ### Optional
 
-- `environment_scope` (String) The environment scope of the variable. Defaults to all environment (`*`). Note that in Community Editions of Gitlab, values other than `*` will cause inconsistent plans.
+- `environment_scope` (String) The environment scope of the variable. Defaults to all environment (`*`).
 
 ### Read-Only
 
-- `description` (String) The description of the variable.
-- `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/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`.
-- `raw` (Boolean) Whether the variable is treated as a raw string. Default: false. When true, variables in the value are not expanded.
+- `description` (String) The description of the variable. Maximum of 255 characters.
+- `id` (String) The ID of this datasource. In the format `<project:key:environment-scope>`.
+- `masked` (Boolean) If set to `true`, the value of the variable will be hidden in job logs.
+- `protected` (Boolean) If set to `true`, the variable will be passed only to pipelines running on protected branches and tags.
+- `raw` (Boolean) If set to `true`, the variable will be treated as a raw string.
 - `value` (String) The value of the variable.
-- `variable_type` (String) The type of a variable. Valid values are: `env_var`, `file`. Default is `env_var`.
+- `variable_type` (String) The type of the variable, either `env_var` or `file`.

docs/development/CreatingANewResource.md

@@ -318,7 +318,7 @@ func (r *gitlabApplicationResource) Create(ctx context.Context, req resource.Cre
 	}
 
 	// Create application
-	application, _, err := r.client.Applications.CreateApplication(options)
+	application, _, err := r.client.Applications.CreateApplication(options, gitlab.WithContext(ctx))
 	if err != nil {
 		resp.Diagnostics.AddError("GitLab API error occurred", fmt.Sprintf("Unable to create application: %s", err.Error()))
 		return
@@ -347,7 +347,7 @@ the input follows terraform best practices.
 will not be passed to the API, and either defaults will be used or the value will not be set by the API.
 4. `if !data.Confidential.IsNull() {...}` checks to see if an optional value is null. If the value is not null, it's added to the `options`
 struct to be passed to the API.
-5. `application, _, err := r.client.Applications.CreateApplication(options)` calls the API with the input options to create the application.
+5. `application, _, err := r.client.Applications.CreateApplication(options, gitlab.WithContext(ctx))` calls the API with the input options to create the application.
 6. Just like in the `Read` func, `r.applicationModelToState(application, data)` sets the newly created application into the data object
 7. Finally, like in the `Read` func, `resp.Diagnostics.Append(resp.State.Set(ctx, &data)...)` sets the data into state.
 

docs/index.md

@@ -20,6 +20,8 @@ We support the following versions:
 
 All other versions are best effort support.
 
+We do not support experimental GitLab features until they are enabled by default or made Generally Available.
+
 -> Note, that the compatibility between a provider release and GitLab itself **cannot** be inferred from the
 release version. New features added to GitLab may not be added to the provider until later versions.
 Equally, features removed or deprecated in GitLab may not be removed or deprecated from the provider until later versions.
@@ -32,9 +34,18 @@ 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 
+-> 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. 
+Personal Access Token or Service Account if you are experiencing permission errors when adding resources.
+
+## Authentication and Configuration
+
+The configuration for the GitLab Provider can be derived from several sources,
+which are applied in the following order:
+
+1. Attributes in the provider configuration (see Schema section below)
+2. Environment variables (see Schema section below)
+3. (experimental) Configuration file (see https://gitlab.com/gitlab-org/api/client-go#use-the-config-package-experimental)
 
 ## Example Usage
 
@@ -92,7 +103,10 @@ resource "gitlab_project" "sample_group_project" {
 - `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.
+- `config_file` (String) The path to the configuration file to use. It may be sourced from the `GITLAB_CONFIG_FILE` environment variable.
+- `context` (String) The context to use for authentication and configuration. The context must exist in the configuration file. It may be sourced from the `GITLAB_CONTEXT` environment variable.
 - `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. It may be sourced from the `GITLAB_EARLY_AUTH_CHECK`. This is an experimental feature and may change in the future. Please make sure to always keep backups of your state.
+- `enable_auto_ci_support` (Boolean) If automatic CI support should be enabled or not. This only works when not providing a token.
 - `headers` (Map of String) A map of headers to append to all API request to the GitLab instance.
 - `insecure` (Boolean) When set to true this disables SSL verification of the connection to the GitLab instance.
 - `retries` (Number) The number of retries to execute when receiving a 429 Rate Limit error. Each retry will exponentially back off.

docs/resources/cluster_agent.md

@@ -63,7 +63,7 @@ resource "gitlab_repository_file" "example_agent_config" {
 - `agent_id` (Number) The ID of the agent.
 - `created_at` (String) The ISO8601 datetime when the agent was created.
 - `created_by_user_id` (Number) The ID of the user who created the agent.
-- `id` (String) The ID of this resource.
+- `id` (String) The ID of this resource. In the format <project:agent_id>
 
 ## Import