Skip to content

Commit fb2e42d

Browse files
timofurrertimofurrer
authored
Merge pull request #921 from timofurrer/docs/descriptions
Improve documentation and reference upstream API for every data source and resource
2 parents fbbcb72 + c4cfe2b commit fb2e42d

File tree

110 files changed

+544
-338
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

110 files changed

+544
-338
lines changed

‎docs/data-sources/branch.md

+5-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,15 @@
33
page_title: "gitlab_branch Data Source - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
Provide details about a gitlab project branch
6+
The gitlab_branch data source allows details of a repository branch to be retrieved by its name and project.
7+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/branches.html#get-single-repository-branch
78
---
89

910
# gitlab_branch (Data Source)
1011

11-
Provide details about a gitlab project branch
12+
The `gitlab_branch` data source allows details of a repository branch to be retrieved by its name and project.
13+
14+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/branches.html#get-single-repository-branch)
1215

1316
## Example Usage
1417

‎docs/data-sources/group.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,15 @@
33
page_title: "gitlab_group Data Source - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
Provide details about a specific group in the gitlab provider.
7-
Note: exactly one of groupid or fullpath must be provided.
6+
The gitlab_group data source allows details of a group to be retrieved by its id or full path.
7+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/groups.html#details-of-a-group
88
---
99

1010
# gitlab_group (Data Source)
1111

12-
Provide details about a specific group in the gitlab provider.
12+
The `gitlab_group` data source allows details of a group to be retrieved by its id or full path.
1313

14-
> **Note**: exactly one of group_id or full_path must be provided.
14+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/groups.html#details-of-a-group)
1515

1616
## Example Usage
1717

‎docs/data-sources/group_membership.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,15 @@
33
page_title: "gitlab_group_membership Data Source - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
Provide details about a list of group members in the gitlab provider. The results include id, username, name and more about the requested members.
7-
Note: exactly one of groupid or fullpath must be provided.
6+
The gitlab_group_membership data source allows to list and filter all members of a group specified by either its id or full path.
7+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/members.html#list-all-members-of-a-group-or-project
88
---
99

1010
# gitlab_group_membership (Data Source)
1111

12-
Provide details about a list of group members in the gitlab provider. The results include id, username, name and more about the requested members.
12+
The `gitlab_group_membership` data source allows to list and filter all members of a group specified by either its id or full path.
1313

14-
> **Note**: exactly one of group_id or full_path must be provided.
14+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/members.html#list-all-members-of-a-group-or-project)
1515

1616
## Example Usage
1717

‎docs/data-sources/project.md

+5-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,15 @@
33
page_title: "gitlab_project Data Source - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
Provide details about a specific project in the gitlab provider. The results include the name of the project, path, description, default branch, etc.
6+
The gitlab_project data source allows details of a project to be retrieved by either its ID or its path with namespace.
7+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/projects.html#get-single-project
78
---
89

910
# gitlab_project (Data Source)
1011

11-
Provide details about a specific project in the gitlab provider. The results include the name of the project, path, description, default branch, etc.
12+
The `gitlab_project` data source allows details of a project to be retrieved by either its ID or its path with namespace.
13+
14+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/projects.html#get-single-project)
1215

1316
## Example Usage
1417

‎docs/data-sources/project_protected_branch.md

+5-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,15 @@
33
page_title: "gitlab_project_protected_branch Data Source - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
Provides details about a specific protected branch in a given project.
6+
The gitlab_protected_branch data source allows details of a protected branch to be retrieved by its name and the project it belongs to.
7+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/protected_branches.html#get-a-single-protected-branch-or-wildcard-protected-branch
78
---
89

910
# gitlab_project_protected_branch (Data Source)
1011

11-
Provides details about a specific protected branch in a given project.
12+
The `gitlab_protected_branch` data source allows details of a protected branch to be retrieved by its name and the project it belongs to.
13+
14+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/protected_branches.html#get-a-single-protected-branch-or-wildcard-protected-branch)
1215

1316
## Example Usage
1417

‎docs/data-sources/project_protected_branches.md

+5-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,15 @@
33
page_title: "gitlab_project_protected_branches Data Source - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
Provides details about all protected branches in a given project.
6+
The gitlab_protected_branches data source allows details of the protected branches of a given project.
7+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/protected_branches.html#list-protected-branches
78
---
89

910
# gitlab_project_protected_branches (Data Source)
1011

11-
Provides details about all protected branches in a given project.
12+
The `gitlab_protected_branches` data source allows details of the protected branches of a given project.
13+
14+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/protected_branches.html#list-protected-branches)
1215

1316
## Example Usage
1417

‎docs/data-sources/projects.md

+9-6
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,21 @@
33
page_title: "gitlab_projects Data Source - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
Provide details about a list of projects in the Gitlab provider. Listing all projects and group projects with project filtering https://docs.gitlab.com/ee/api/projects.html#list-user-projects or group project filtering https://docs.gitlab.com/ee/api/groups.html#list-a-groups-projects is supported.
7-
NOTE: This data source supports all available filters exposed by the xanzy/go-gitlab package, which might not expose all available filters exposed by the Gitlab APIs.
8-
NOTE: The owner sub-attributes are only populated if the Gitlab token used has an administrator scope.
6+
The gitlab_projects data source allows details of multiple projects to be retrieved. Optionally filtered by the set attributes.
7+
-> This data source supports all available filters exposed by the xanzy/go-gitlab package, which might not expose all available filters exposed by the Gitlab APIs.
8+
-> The owner sub-attributes are only populated if the Gitlab token used has an administrator scope.
9+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/projects.html#list-all-projects
910
---
1011

1112
# gitlab_projects (Data Source)
1213

13-
Provide details about a list of projects in the Gitlab provider. Listing all projects and group projects with [project filtering](https://docs.gitlab.com/ee/api/projects.html#list-user-projects) or [group project filtering](https://docs.gitlab.com/ee/api/groups.html#list-a-groups-projects) is supported.
14+
The `gitlab_projects` data source allows details of multiple projects to be retrieved. Optionally filtered by the set attributes.
1415

15-
> **NOTE**: This data source supports all available filters exposed by the `xanzy/go-gitlab` package, which might not expose all available filters exposed by the Gitlab APIs.
16+
-> This data source supports all available filters exposed by the xanzy/go-gitlab package, which might not expose all available filters exposed by the Gitlab APIs.
1617

17-
> **NOTE**: The [owner sub-attributes](#nestedobjatt--projects--owner) are only populated if the Gitlab token used has an administrator scope.
18+
-> The [owner sub-attributes](#nestedobjatt--projects--owner) are only populated if the Gitlab token used has an administrator scope.
19+
20+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/projects.html#list-all-projects)
1821

1922
## Example Usage
2023

‎docs/data-sources/user.md

+7-4
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,18 @@
33
page_title: "gitlab_user Data Source - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
Provide details about a specific user in the gitlab provider. Especially the ability to lookup the id for linking to other resources.
7-
-> Some attributes might not be returned depending on if you're an admin or not. Please refer to Gitlab documentation https://docs.gitlab.com/ce/api/users.html#single-user for more details.
6+
The gitlab_user data source allows details of a user to be retrieved by either the user ID, username or email address.
7+
-> Some attributes might not be returned depending on if you're an admin or not.
8+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/users.html#single-user
89
---
910

1011
# gitlab_user (Data Source)
1112

12-
Provide details about a specific user in the gitlab provider. Especially the ability to lookup the id for linking to other resources.
13+
The `gitlab_user` data source allows details of a user to be retrieved by either the user ID, username or email address.
1314

14-
-> Some attributes might not be returned depending on if you're an admin or not. Please refer to [Gitlab documentation](https://docs.gitlab.com/ce/api/users.html#single-user) for more details.
15+
-> Some attributes might not be returned depending on if you're an admin or not.
16+
17+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/users.html#single-user)
1518

1619
## Example Usage
1720

‎docs/data-sources/users.md

+10-4
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,21 @@
33
page_title: "gitlab_users Data Source - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
Provide details about a list of users in the gitlab provider. The results include id, username, email, name and more about the requested users. Users can also be sorted and filtered using several options.
7-
NOTE: Some available options require administrator privileges. Please visit [Gitlab API documentation][usersforadmins] for more information.
6+
The gitlab_users data source allows details of multiple users to be retrieved given some optional filter criteria.
7+
-> Some attributes might not be returned depending on if you're an admin or not.
8+
-> Some available options require administrator privileges.
9+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ce/api/users.html#list-users
810
---
911

1012
# gitlab_users (Data Source)
1113

12-
Provide details about a list of users in the gitlab provider. The results include id, username, email, name and more about the requested users. Users can also be sorted and filtered using several options.
14+
The `gitlab_users` data source allows details of multiple users to be retrieved given some optional filter criteria.
1315

14-
**NOTE**: Some available options require administrator privileges. Please visit [Gitlab API documentation][users_for_admins] for more information.
16+
-> Some attributes might not be returned depending on if you're an admin or not.
17+
18+
-> Some available options require administrator privileges.
19+
20+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ce/api/users.html#list-users)
1521

1622
## Example Usage
1723

‎docs/index.md

+6
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,12 @@ Use the GitLab provider to interact with GitLab resources, like
99
users, groups, projects and more. You must configure the provider with
1010
the proper credentials before you can use it.
1111

12+
The provider uses the [`xanzy/go-gitlab`](https://github.com/xanzy/go-gitlab) library
13+
to interact with the [GitLab REST API](https://docs.gitlab.com/ee/api/api_resources.html).
14+
15+
Each data source and resource references the appropriate upstream GitLab REST API documentation,
16+
which may be consumed to better understand the behavior of the API.
17+
1218
Use the navigation to the left to read about the valid data sources and resources.
1319

1420
This provider requires at least [Terraform 0.12](https://www.terraform.io/downloads.html).

‎docs/resources/branch.md

+5-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,15 @@
33
page_title: "gitlab_branch Resource - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
This resource allows you to create and manage GitLab branches.
6+
The gitlab_branch resource allows to manage the lifecycle of a repository branch.
7+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/branches.html
78
---
89

910
# gitlab_branch (Resource)
1011

11-
This resource allows you to create and manage GitLab branches.
12+
The `gitlab_branch` resource allows to manage the lifecycle of a repository branch.
13+
14+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/branches.html)
1215

1316
## Example Usage
1417

‎docs/resources/branch_protection.md

+7-4
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,18 @@
33
page_title: "gitlab_branch_protection Resource - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
This resource allows you to protect a specific branch by an access level so that the user with less access level cannot Merge/Push to the branch.
7-
-> The allowed_to_push, allowed_to_merge and code_owner_approval_required arguments require a GitLab Premium account or above. Please refer to Gitlab API documentation https://docs.gitlab.com/ee/api/protected_branches.html for further information.
6+
The gitlab_branch_protection resource allows to manage the lifecycle of a protected branch of a repository.
7+
~> The allowedtopush, allowedtomerge and codeownerapproval_required attributes require a GitLab Enterprise instance.
8+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/protected_branches.html
89
---
910

1011
# gitlab_branch_protection (Resource)
1112

12-
This resource allows you to protect a specific branch by an access level so that the user with less access level cannot Merge/Push to the branch.
13+
The `gitlab_branch_protection` resource allows to manage the lifecycle of a protected branch of a repository.
1314

14-
-> The `allowed_to_push`, `allowed_to_merge` and `code_owner_approval_required` arguments require a GitLab Premium account or above. Please refer to [Gitlab API documentation](https://docs.gitlab.com/ee/api/protected_branches.html) for further information.
15+
~> The allowed_to_push, allowed_to_merge and code_owner_approval_required attributes require a GitLab Enterprise instance.
16+
17+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/protected_branches.html)
1518

1619
## Example Usage
1720

‎docs/resources/deploy_key.md

+8-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,18 @@
33
page_title: "gitlab_deploy_key Resource - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
This resource allows you to create and manage deploy keys https://docs.gitlab.com/ee/user/project/deploy_keys/ for your GitLab projects.
6+
The gitlab_deploy_key resource allows to manage the lifecycle of a deploy key.
7+
-> To enable an already existing deploy key for another project use the gitlab_project_deploy_key resource.
8+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/deploy_keys.html
79
---
810

911
# gitlab_deploy_key (Resource)
1012

11-
This resource allows you to create and manage [deploy keys](https://docs.gitlab.com/ee/user/project/deploy_keys/) for your GitLab projects.
13+
The `gitlab_deploy_key` resource allows to manage the lifecycle of a deploy key.
14+
15+
-> To enable an already existing deploy key for another project use the `gitlab_project_deploy_key` resource.
16+
17+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/deploy_keys.html)
1218

1319
## Example Usage
1420

‎docs/resources/deploy_key_enable.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,15 @@
33
page_title: "gitlab_deploy_key_enable Resource - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
This resource allows you to enable pre-existing deploy keys for your GitLab projects.
7-
NOTE: the GITLAB KEY_ID for the deploy key must be known
6+
The gitlab_deploy_key_enable resource allows to enable an already existing deploy key (see gitlab_deploy_key resource) for a specific project.
7+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/deploy_keys.html#enable-a-deploy-key
88
---
99

1010
# gitlab_deploy_key_enable (Resource)
1111

12-
This resource allows you to enable pre-existing deploy keys for your GitLab projects.
12+
The `gitlab_deploy_key_enable` resource allows to enable an already existing deploy key (see `gitlab_deploy_key resource`) for a specific project.
1313

14-
> **NOTE**: the GITLAB KEY_ID for the deploy key must be known
14+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/deploy_keys.html#enable-a-deploy-key)
1515

1616
## Example Usage
1717

‎docs/resources/deploy_token.md

+5-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,15 @@
33
page_title: "gitlab_deploy_token Resource - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
This resource allows you to create and manage deploy token for your GitLab projects and groups. Please refer to Gitlab documentation https://docs.gitlab.com/ee/user/project/deploy_tokens/ for further information.
6+
The gitlab_deploy_token resource allows to manage the lifecycle of group and project deploy tokens.
7+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/deploy_tokens.html
78
---
89

910
# gitlab_deploy_token (Resource)
1011

11-
This resource allows you to create and manage deploy token for your GitLab projects and groups. Please refer to [Gitlab documentation](https://docs.gitlab.com/ee/user/project/deploy_tokens/) for further information.
12+
The `gitlab_deploy_token` resource allows to manage the lifecycle of group and project deploy tokens.
13+
14+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/deploy_tokens.html)
1215

1316
## Example Usage
1417

‎docs/resources/group_access_token.md

+8-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,18 @@
33
page_title: "gitlab_group_access_token Resource - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
This resource allows you to create and manage Group Access Token for your GitLab Groups. (Introduced in GitLab 14.7)
6+
The gitlab_group_accesstoken resource allows to manage the lifecycle of a group access token.
7+
-> Group Access Token were introduced in GitLab 14.7
8+
Upstream API: GitLab REST API https://docs.gitlab.com/ee/api/group_access_tokens.html
79
---
810

911
# gitlab_group_access_token (Resource)
1012

11-
This resource allows you to create and manage Group Access Token for your GitLab Groups. (Introduced in GitLab 14.7)
13+
The `gitlab_group_access`token resource allows to manage the lifecycle of a group access token.
14+
15+
-> Group Access Token were introduced in GitLab 14.7
16+
17+
**Upstream API**: [GitLab REST API](https://docs.gitlab.com/ee/api/group_access_tokens.html)
1218

1319
## Example Usage
1420

‎docs/resources/group_badge.md

+5-6
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,15 @@
33
page_title: "gitlab_group_badge Resource - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
This resource allows you to create and manage badges for your GitLab groups.
7-
For further information, consult the gitlab
8-
documentation https://docs.gitlab.com/ee/user/project/badges.html#group-badges.
6+
The gitlab_group_badge resource allows to mange the lifecycle of group badges.
7+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/user/project/badges.html#group-badges
98
---
109

1110
# gitlab_group_badge (Resource)
1211

13-
This resource allows you to create and manage badges for your GitLab groups.
14-
For further information, consult the [gitlab
15-
documentation](https://docs.gitlab.com/ee/user/project/badges.html#group-badges).
12+
The `gitlab_group_badge` resource allows to mange the lifecycle of group badges.
13+
14+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/user/project/badges.html#group-badges)
1615

1716
## Example Usage
1817

‎docs/resources/group_cluster.md

+8-6
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,18 @@
33
page_title: "gitlab_group_cluster Resource - terraform-provider-gitlab"
44
subcategory: ""
55
description: |-
6-
This resource allows you to create and manage group clusters for your GitLab groups.
7-
For further information on clusters, consult the gitlab
8-
documentation https://docs.gitlab.com/ce/user/group/clusters/index.html.
6+
The gitlab_group_cluster resource allows to manage the lifecycle of a group cluster.
7+
~> This is deprecated GitLab feature since 14.5
8+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/group_clusters.html
99
---
1010

1111
# gitlab_group_cluster (Resource)
1212

13-
This resource allows you to create and manage group clusters for your GitLab groups.
14-
For further information on clusters, consult the [gitlab
15-
documentation](https://docs.gitlab.com/ce/user/group/clusters/index.html).
13+
The `gitlab_group_cluster` resource allows to manage the lifecycle of a group cluster.
14+
15+
~> This is deprecated GitLab feature since 14.5
16+
17+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/group_clusters.html)
1618

1719
## Example Usage
1820

0 commit comments

Comments
 (0)