From 0d3ab1e68ab2b9f69a0b4052f6ac2ed4b2c835a7 Mon Sep 17 00:00:00 2001 From: Steve Hipwell Date: Mon, 18 May 2026 17:01:13 +0100 Subject: [PATCH] docs: Update repository collaborators resource docs Signed-off-by: Steve Hipwell --- docs/resources/repository_collaborators.md | 103 +++++++++++++----- .../import-by-string-id.tf | 4 + .../github_repository_collaborators/import.sh | 1 + .../resource_1.tf} | 0 ...esource_github_repository_collaborators.go | 28 +++-- .../repository_collaborators.md.tmpl | 83 ++++++++------ 6 files changed, 145 insertions(+), 74 deletions(-) create mode 100644 examples/resources/github_repository_collaborators/import-by-string-id.tf create mode 100644 examples/resources/github_repository_collaborators/import.sh rename examples/resources/{repository_collaborators/example_1.tf => github_repository_collaborators/resource_1.tf} (100%) diff --git a/docs/resources/repository_collaborators.md b/docs/resources/repository_collaborators.md index b6f4d67ace..91e172a0ce 100644 --- a/docs/resources/repository_collaborators.md +++ b/docs/resources/repository_collaborators.md @@ -1,24 +1,41 @@ --- page_title: "github_repository_collaborators (Resource) - GitHub" +subcategory: "" description: |- - Provides a GitHub repository collaborators resource. + Manage the complete set of collaborators (users and teams) for a GitHub repository. --- # github_repository_collaborators (Resource) -Provides a GitHub repository collaborators resource. +Manage the complete set of collaborators (users and teams) for a GitHub repository. -~> Note: github_repository_collaborators cannot be used in conjunction with github_repository_collaborator and github_team_repository or they will fight over what your policy should be. +~> This resource (`github_repository_collaborators`) cannot be used in conjunction with [`github_repository_collaborator`](repository_collaborator) or [`github_team_repository`](team_repository) as they will conflict over the management of collaborators. -This resource allows you to manage all collaborators for repositories in your organization or personal account. For organization repositories, collaborators can have explicit (and differing levels of) read, write, or administrator access to specific repositories, without giving the user full organization membership. For personal repositories, collaborators can only be granted write (implicitly includes read) permission. +This resource manages the complete set of collaborators for a repository, which includes both users and teams, in an authoritative manner. When applied, the provider will ensure that the set of collaborators for the repository matches the set defined in Terraform configuration. This means that if a collaborator is removed from the configuration, it will be removed from the repository, and if a collaborator is added to the configuration, it will be added to the repository. -When applied, an invitation will be sent to the user to become a collaborators on a repository. When destroyed, either the invitation will be cancelled or the collaborators will be removed from the repository. +~> **Archived Repositories** When a repository is archived, GitHub makes it read-only, preventing collaborator modifications. If you attempt to destroy resources associated with archived repositories, the provider will gracefully handle the operation by logging an informational message and removing the resource from Terraform state without attempting to modify the archived repository. + +## Organization Repositories + +For repositories owned by an organization, collaborators can have explicit (and differing levels of) read, write, or administrator access to specific repositories, without giving the user full organization membership. + +### Teams -~> **Note on Archived Repositories**: When a repository is archived, GitHub makes it read-only, preventing collaborator modifications. If you attempt to destroy resources associated with archived repositories, the provider will gracefully handle the operation by logging an informational message and removing the resource from Terraform state without attempting to modify the archived repository. +Teams will be added to the repository on apply, and removed if removed from the configuration or on destroy. Teams added to the repository outside of Terraform can be managed by adding them to the configuration, or ignored by using the `ignore_team` argument. This is particularly important for organization/enterprise teams, which either need to be added to the configuration or ignored, as otherwise they will cause perpetual drift. -This resource is authoritative. For adding a collaborator to a repo in a non-authoritative manner, use github_repository_collaborator instead. +## Personal Repositories -Further documentation on GitHub collaborators: +For personal repositories, collaborators can only be granted [write](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/repository-access-and-collaboration/permission-levels-for-a-personal-account-repository#collaborator-access-for-a-repository-owned-by-a-personal-account) permission. + +!> If the repository owner is not added as a collaborator with admin access, the provider will churn this resource on every plan/apply. To prevent this, ensure that the repository owner is included in the set of user collaborators. + +## Users + +When applied, an invitation will be sent to the user to become a collaborators on a repository. When destroyed, either the invitation will be cancelled or the collaborators will be removed from the repository. + +## Documentation + +Further documentation on GitHub collaborators. - [Adding outside collaborators to your personal repositories](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/managing-access-to-your-personal-repositories) - [Adding outside collaborators to repositories in your organization](https://help.github.com/articles/adding-outside-collaborators-to-repositories-in-your-organization/) @@ -52,39 +69,71 @@ resource "github_repository_collaborators" "some_repo_collaborators" { } ``` -## Argument Reference + +## Schema + +### Required + +- `repository` (String) Name of the repository. + +### Optional -The following arguments are supported: +- `ignore_team` (Block Set) Teams to ignore when managing repository collaborators. (see [below for nested schema](#nestedblock--ignore_team)) +- `team` (Block Set) Teams to grant access to the repository. (see [below for nested schema](#nestedblock--team)) +- `user` (Block Set) Users to grant access to the repository. (see [below for nested schema](#nestedblock--user)) -- `repository` - (Required) The GitHub repository. -- `user` - (Optional) List of users to grant access to the repository. -- `team` - (Optional) List of teams to grant access to the repository. -- `ignore_team` - (Optional) List of teams to ignore when checking for repository access. This supports ignoring teams granted access at an organizational level. +### Read-Only -The `user` block supports: +- `id` (String) The ID of this resource. +- `invitation_ids` (Map of String) Map of usernames to invitation ID for users that haven't yet accepted their invitation to become a collaborator. This is only set on read, and is used internally to track pending invitations for users that aren't yet collaborators. +- `repository_id` (Number) ID of the repository. -- `username` - (Required) The user to add to the repository as a collaborator. -- `permission` - (Optional) The permission of the outside collaborators for the repository. Must be one of `pull`, `push`, `maintain`, `triage` or `admin` or the name of an existing [custom repository role](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) within the organization for organization-owned repositories. Must be `push` for personal repositories. Defaults to `push`. + +### Nested Schema for `ignore_team` -The `team` block supports: +Required: -- `team_id` - (Required) The GitHub team id or the GitHub team slug. -- `permission` - (Optional) The permission of the outside collaborators for the repository. Must be one of `pull`, `triage`, `push`, `maintain`, `admin` or the name of an existing [custom repository role](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) within the organisation. Defaults to `pull`. Must be `push` for personal repositories. Defaults to `push`. +- `team_id` (String) ID or slug of the team to ignore. -The `ignore_team` block supports: -- `team_id` - (Required) The GitHub team id or the GitHub team slug. + +### Nested Schema for `team` -## Attribute Reference +Required: -In addition to the above arguments, the following attributes are exported: +- `team_id` (String) ID or slug of the team to add to the repository as a collaborator. -- `invitation_ids` - Map of usernames to invitation ID for any users added as part of creation of this resource to be used in `github_user_invitation_accepter`. +Optional: + +- `permission` (String) Permission to grant to the team. Must be one of `pull`, `triage`, `push`, `maintain`, `admin` or the name of an existing [custom repository role](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) within the organization. Defaults to `push`. + + + +### Nested Schema for `user` + +Required: + +- `username` (String) Login for the user to add to the repository as a collaborator. + +Optional: + +- `permission` (String) Permission to grant to the user. Must be one of `pull`, `triage`, `push`, `maintain`, `admin` or the name of an existing [custom repository role](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) within the organization. Must be `push` for personal repositories. Defaults to `push`. ## Import -GitHub Repository Collaborators can be imported using the name `name`, e.g. +Import is supported using the following syntax: + +In Terraform v1.5.0 and later, the [`import` block](https://developer.hashicorp.com/terraform/language/import) can be used with the `id` attribute, for example: + +```terraform +import { + to = github_repository_collaborators.collaborators + id = "example-repo" +} +``` + +The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell -terraform import github_repository_collaborators.collaborators terraform +terraform import github_repository_collaborators.collaborators example-repo ``` diff --git a/examples/resources/github_repository_collaborators/import-by-string-id.tf b/examples/resources/github_repository_collaborators/import-by-string-id.tf new file mode 100644 index 0000000000..eeaf8cdc00 --- /dev/null +++ b/examples/resources/github_repository_collaborators/import-by-string-id.tf @@ -0,0 +1,4 @@ +import { + to = github_repository_collaborators.collaborators + id = "example-repo" +} diff --git a/examples/resources/github_repository_collaborators/import.sh b/examples/resources/github_repository_collaborators/import.sh new file mode 100644 index 0000000000..bc62b5aeb1 --- /dev/null +++ b/examples/resources/github_repository_collaborators/import.sh @@ -0,0 +1 @@ +terraform import github_repository_collaborators.collaborators example-repo diff --git a/examples/resources/repository_collaborators/example_1.tf b/examples/resources/github_repository_collaborators/resource_1.tf similarity index 100% rename from examples/resources/repository_collaborators/example_1.tf rename to examples/resources/github_repository_collaborators/resource_1.tf diff --git a/github/resource_github_repository_collaborators.go b/github/resource_github_repository_collaborators.go index 6057cf77b0..f776afed47 100644 --- a/github/resource_github_repository_collaborators.go +++ b/github/resource_github_repository_collaborators.go @@ -27,6 +27,8 @@ func resourceGithubRepositoryCollaborators() *schema.Resource { }, }, + Description: "Manage the complete set of collaborators (users and teams) for a GitHub repository.", + CreateContext: resourceGithubRepositoryCollaboratorsCreate, ReadContext: resourceGithubRepositoryCollaboratorsRead, UpdateContext: resourceGithubRepositoryCollaboratorsUpdate, @@ -49,19 +51,20 @@ func resourceGithubRepositoryCollaborators() *schema.Resource { "user": { Type: schema.TypeSet, Optional: true, - Description: "List of users.", + Description: "Users to grant access to the repository.", Elem: &schema.Resource{ Schema: map[string]*schema.Schema{ "username": { Type: schema.TypeString, - Description: "(Required) The user to add to the repository as a collaborator.", + Description: "Login for the user to add to the repository as a collaborator.", Required: true, DiffSuppressFunc: caseInsensitive(), }, "permission": { - Type: schema.TypeString, - Optional: true, - Default: "push", + Type: schema.TypeString, + Description: "Permission to grant to the user. Must be one of `pull`, `triage`, `push`, `maintain`, `admin` or the name of an existing [custom repository role](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) within the organization. Must be `push` for personal repositories. Defaults to `push`.", + Optional: true, + Default: "push", }, }, }, @@ -69,25 +72,26 @@ func resourceGithubRepositoryCollaborators() *schema.Resource { "team": { Type: schema.TypeSet, Optional: true, - Description: "List of teams.", + Description: "Teams to grant access to the repository.", Elem: &schema.Resource{ Schema: map[string]*schema.Schema{ "team_id": { Type: schema.TypeString, - Description: "Team ID or slug to add to the repository as a collaborator.", + Description: "ID or slug of the team to add to the repository as a collaborator.", Required: true, }, "permission": { - Type: schema.TypeString, - Optional: true, - Default: "push", + Type: schema.TypeString, + Description: "Permission to grant to the team. Must be one of `pull`, `triage`, `push`, `maintain`, `admin` or the name of an existing [custom repository role](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) within the organization. Defaults to `push`.", + Optional: true, + Default: "push", }, }, }, }, "invitation_ids": { Type: schema.TypeMap, - Description: "Map of usernames to invitation ID for any users added", + Description: "Map of usernames to invitation ID for users that haven't yet accepted their invitation to become a collaborator. This is only set on read, and is used internally to track pending invitations for users that aren't yet collaborators.", Elem: &schema.Schema{ Type: schema.TypeString, }, @@ -96,7 +100,7 @@ func resourceGithubRepositoryCollaborators() *schema.Resource { "ignore_team": { Type: schema.TypeSet, Optional: true, - Description: "List of teams to ignore.", + Description: "Teams to ignore when managing repository collaborators.", Elem: &schema.Resource{ Schema: map[string]*schema.Schema{ "team_id": { diff --git a/templates/resources/repository_collaborators.md.tmpl b/templates/resources/repository_collaborators.md.tmpl index fe743196d0..a5ba97f83b 100644 --- a/templates/resources/repository_collaborators.md.tmpl +++ b/templates/resources/repository_collaborators.md.tmpl @@ -1,66 +1,79 @@ --- page_title: "{{.Name}} ({{.Type}}) - {{.RenderedProviderName}}" +subcategory: "" description: |- - Provides a GitHub repository collaborators resource. +{{ .Description | plainmarkdown | trimspace | prefixlines " " }} --- # {{.Name}} ({{.Type}}) -Provides a GitHub repository collaborators resource. +{{ .Description | trimspace }} -~> Note: github_repository_collaborators cannot be used in conjunction with github_repository_collaborator and github_team_repository or they will fight over what your policy should be. +~> This resource (`github_repository_collaborators`) cannot be used in conjunction with [`github_repository_collaborator`](repository_collaborator) or [`github_team_repository`](team_repository) as they will conflict over the management of collaborators. -This resource allows you to manage all collaborators for repositories in your organization or personal account. For organization repositories, collaborators can have explicit (and differing levels of) read, write, or administrator access to specific repositories, without giving the user full organization membership. For personal repositories, collaborators can only be granted write (implicitly includes read) permission. +This resource manages the complete set of collaborators for a repository, which includes both users and teams, in an authoritative manner. When applied, the provider will ensure that the set of collaborators for the repository matches the set defined in Terraform configuration. This means that if a collaborator is removed from the configuration, it will be removed from the repository, and if a collaborator is added to the configuration, it will be added to the repository. -When applied, an invitation will be sent to the user to become a collaborators on a repository. When destroyed, either the invitation will be cancelled or the collaborators will be removed from the repository. +~> **Archived Repositories** When a repository is archived, GitHub makes it read-only, preventing collaborator modifications. If you attempt to destroy resources associated with archived repositories, the provider will gracefully handle the operation by logging an informational message and removing the resource from Terraform state without attempting to modify the archived repository. -~> **Note on Archived Repositories**: When a repository is archived, GitHub makes it read-only, preventing collaborator modifications. If you attempt to destroy resources associated with archived repositories, the provider will gracefully handle the operation by logging an informational message and removing the resource from Terraform state without attempting to modify the archived repository. +## Organization Repositories -This resource is authoritative. For adding a collaborator to a repo in a non-authoritative manner, use github_repository_collaborator instead. +For repositories owned by an organization, collaborators can have explicit (and differing levels of) read, write, or administrator access to specific repositories, without giving the user full organization membership. -Further documentation on GitHub collaborators: +### Teams -- [Adding outside collaborators to your personal repositories](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/managing-access-to-your-personal-repositories) -- [Adding outside collaborators to repositories in your organization](https://help.github.com/articles/adding-outside-collaborators-to-repositories-in-your-organization/) -- [Converting an organization member to an outside collaborators](https://help.github.com/articles/converting-an-organization-member-to-an-outside-collaborator/) +Teams will be added to the repository on apply, and removed if removed from the configuration or on destroy. Teams added to the repository outside of Terraform can be managed by adding them to the configuration, or ignored by using the `ignore_team` argument. This is particularly important for organization/enterprise teams, which either need to be added to the configuration or ignored, as otherwise they will cause perpetual drift. -## Example Usage +## Personal Repositories + +For personal repositories, collaborators can only be granted [write](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/repository-access-and-collaboration/permission-levels-for-a-personal-account-repository#collaborator-access-for-a-repository-owned-by-a-personal-account) permission. + +!> If the repository owner is not added as a collaborator with admin access, the provider will churn this resource on every plan/apply. To prevent this, ensure that the repository owner is included in the set of user collaborators. + +## Users -{{ tffile "examples/resources/repository_collaborators/example_1.tf" }} +When applied, an invitation will be sent to the user to become a collaborators on a repository. When destroyed, either the invitation will be cancelled or the collaborators will be removed from the repository. + +## Documentation -## Argument Reference +Further documentation on GitHub collaborators. -The following arguments are supported: +- [Adding outside collaborators to your personal repositories](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/managing-access-to-your-personal-repositories) +- [Adding outside collaborators to repositories in your organization](https://help.github.com/articles/adding-outside-collaborators-to-repositories-in-your-organization/) +- [Converting an organization member to an outside collaborators](https://help.github.com/articles/converting-an-organization-member-to-an-outside-collaborator/) -- `repository` - (Required) The GitHub repository. -- `user` - (Optional) List of users to grant access to the repository. -- `team` - (Optional) List of teams to grant access to the repository. -- `ignore_team` - (Optional) List of teams to ignore when checking for repository access. This supports ignoring teams granted access at an organizational level. +{{ if .HasExamples -}} +## Example Usage -The `user` block supports: +{{- range .ExampleFiles }} -- `username` - (Required) The user to add to the repository as a collaborator. -- `permission` - (Optional) The permission of the outside collaborators for the repository. Must be one of `pull`, `push`, `maintain`, `triage` or `admin` or the name of an existing [custom repository role](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) within the organization for organization-owned repositories. Must be `push` for personal repositories. Defaults to `push`. +{{ tffile . }} +{{- end }} +{{- end }} -The `team` block supports: +{{ .SchemaMarkdown | trimspace }} +{{- if or .HasImport .HasImportIDConfig .HasImportIdentityConfig }} -- `team_id` - (Required) The GitHub team id or the GitHub team slug. -- `permission` - (Optional) The permission of the outside collaborators for the repository. Must be one of `pull`, `triage`, `push`, `maintain`, `admin` or the name of an existing [custom repository role](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) within the organisation. Defaults to `pull`. Must be `push` for personal repositories. Defaults to `push`. +## Import -The `ignore_team` block supports: +Import is supported using the following syntax: +{{- end }} +{{- if .HasImportIdentityConfig }} -- `team_id` - (Required) The GitHub team id or the GitHub team slug. +In Terraform v1.12.0 and later, the [`import` block](https://developer.hashicorp.com/terraform/language/import) can be used with the `identity` attribute, for example: -## Attribute Reference +{{tffile .ImportIdentityConfigFile }} -In addition to the above arguments, the following attributes are exported: +{{ .IdentitySchemaMarkdown | trimspace }} +{{- end }} +{{- if .HasImportIDConfig }} -- `invitation_ids` - Map of usernames to invitation ID for any users added as part of creation of this resource to be used in `github_user_invitation_accepter`. +In Terraform v1.5.0 and later, the [`import` block](https://developer.hashicorp.com/terraform/language/import) can be used with the `id` attribute, for example: -## Import +{{tffile .ImportIDConfigFile }} +{{- end }} +{{- if .HasImport }} -GitHub Repository Collaborators can be imported using the name `name`, e.g. +The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: -```shell -terraform import github_repository_collaborators.collaborators terraform -``` +{{codefile "shell" .ImportFile }} +{{- end }}