From b7fa8659adc0a8597a3642cffc3568a774907e8d Mon Sep 17 00:00:00 2001 From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Date: Wed, 3 Jun 2026 18:50:47 -0700 Subject: [PATCH 1/3] docs: mark private attribute as deprecated in github_repository Migrate github_repository docs to the generated pattern per review: - Copy the documented argument descriptions into the resource schema Description fields (including private, now described as deprecated in favor of visibility) and add a resource-level Description carrying the GitHub App authentication note. - Replace templates/resources/repository.md.tmpl with the generic resource template pattern (front matter from .Description, example loop, generated schema markdown, import section). - Add examples/resources/repository/import.sh for the import section. - Regenerate docs/resources/repository.md via tfplugindocs. Closes #3297 Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/resources/repository.md | 281 ++++++++++-------------- examples/resources/repository/import.sh | 1 + github/resource_github_repository.go | 69 +++--- templates/resources/repository.md.tmpl | 211 +++--------------- 4 files changed, 180 insertions(+), 382 deletions(-) create mode 100644 examples/resources/repository/import.sh diff --git a/docs/resources/repository.md b/docs/resources/repository.md index 58aede34a6..01167f6643 100644 --- a/docs/resources/repository.md +++ b/docs/resources/repository.md @@ -1,7 +1,9 @@ --- page_title: "github_repository (Resource) - GitHub" +subcategory: "" description: |- - Creates and manages repositories within GitHub organizations or personal accounts + This resource allows you to create and manage repositories within your GitHub organization or personal account. + ~> Note When used with GitHub App authentication, even GET requests must have the contents:write permission. Without it, the following arguments will be ignored, leading to unexpected behavior and confusing diffs: allow_merge_commit, allow_squash_merge, allow_rebase_merge, merge_commit_title, merge_commit_message, squash_merge_commit_title and squash_merge_commit_message. --- # github_repository (Resource) @@ -10,218 +12,167 @@ This resource allows you to create and manage repositories within your GitHub or ~> **Note** When used with GitHub App authentication, even GET requests must have the `contents:write` permission. Without it, the following arguments will be ignored, leading to unexpected behavior and confusing diffs: `allow_merge_commit`, `allow_squash_merge`, `allow_rebase_merge`, `merge_commit_title`, `merge_commit_message`, `squash_merge_commit_title` and `squash_merge_commit_message`. -## Example Usage -```terraform -resource "github_repository" "example" { - name = "example" - description = "My awesome codebase" - visibility = "public" + +## Schema + +### Required + +- `name` (String) The name of the repository. - template { - owner = "github" - repository = "terraform-template-module" - include_all_branches = true - } -} -``` +### Optional -## Example Usage with Repository Forking +- `allow_auto_merge` (Boolean) Set to 'true' to allow auto-merging pull requests on the repository. +- `allow_forking` (Boolean) Configure private forking for organization owned private and internal repositories; set to 'true' to enable, 'false' to disable, and leave unset for the default behaviour. Configuring this requires that private forking is not being explicitly configured at the organization level. +- `allow_merge_commit` (Boolean) Set to 'false' to disable merge commits on the repository. +- `allow_rebase_merge` (Boolean) Set to 'false' to disable rebase merges on the repository. +- `allow_squash_merge` (Boolean) Set to 'false' to disable squash merges on the repository. +- `allow_update_branch` (Boolean) Set to 'true' to always suggest updating pull request branches. +- `archive_on_destroy` (Boolean) Set to 'true' to archive the repository instead of deleting on destroy. +- `archived` (Boolean) Specifies if the repository should be archived. Defaults to 'false'. NOTE Currently, the API does not support unarchiving. +- `auto_init` (Boolean) Set to 'true' to produce an initial commit in the repository. +- `default_branch` (String, Deprecated) The name of the default branch of the repository. NOTE: This can only be set after a repository has already been created, and after a correct reference has been created for the target branch inside the repository. This means a user will have to omit this parameter from the initial repository creation and create the target branch inside of the repository prior to setting this attribute. +- `delete_branch_on_merge` (Boolean) Automatically delete head branch after a pull request is merged. Defaults to 'false'. +- `description` (String) A description of the repository. +- `etag` (String) An etag representing the repository object. +- `fork` (String) Set to 'true' to create a fork of an existing repository. When set to 'true', both 'source_owner' and 'source_repo' must also be specified. +- `gitignore_template` (String) Use the name of the template without the extension. For example, 'Haskell'. +- `has_discussions` (Boolean) Set to 'true' to enable GitHub Discussions on the repository. Defaults to 'false'. +- `has_downloads` (Boolean, Deprecated) Set to 'true' to enable the (deprecated) downloads features on the repository. +- `has_issues` (Boolean) Set to 'true' to enable the GitHub Issues features on the repository. +- `has_projects` (Boolean) Set to 'true' to enable the GitHub Projects features on the repository. Per the GitHub [documentation](https://developer.github.com/v3/repos/#create) when in an organization that has disabled repository projects it will default to 'false' and will otherwise default to 'true'. If you specify 'true' when it has been disabled it will return an error. +- `has_wiki` (Boolean) Set to 'true' to enable the GitHub Wiki features on the repository. +- `homepage_url` (String) URL of a page describing the project. +- `ignore_vulnerability_alerts_during_read` (Boolean, Deprecated) This is ignored as the provider now handles lack of permissions automatically. This field will be removed in a future version. +- `is_template` (Boolean) Set to 'true' to tell GitHub that this is a template repository. +- `license_template` (String) Use the name of the template without the extension. For example, 'mit' or 'mpl-2.0'. +- `merge_commit_message` (String) Can be 'PR_BODY', 'PR_TITLE', or 'BLANK' for a default merge commit message. Applicable only if 'allow_merge_commit' is 'true'. +- `merge_commit_title` (String) Can be 'PR_TITLE' or 'MERGE_MESSAGE' for a default merge commit title. Applicable only if 'allow_merge_commit' is 'true'. +- `pages` (Block List, Max: 1, Deprecated) The repository's GitHub Pages configuration. (see [below for nested schema](#nestedblock--pages)) +- `private` (Boolean, Deprecated) Set to 'true' to create a private repository. Repositories are created as public (e.g. open source) by default. Deprecated: use visibility instead. +- `security_and_analysis` (Block List, Max: 1) The repository's [security and analysis](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository) configuration. To use this parameter you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. (see [below for nested schema](#nestedblock--security_and_analysis)) +- `source_owner` (String) The GitHub username or organization that owns the repository being forked. Required when 'fork' is 'true'. +- `source_repo` (String) The name of the repository to fork. Required when 'fork' is 'true'. +- `squash_merge_commit_message` (String) Can be 'PR_BODY', 'COMMIT_MESSAGES', or 'BLANK' for a default squash merge commit message. Applicable only if 'allow_squash_merge' is 'true'. +- `squash_merge_commit_title` (String) Can be 'PR_TITLE' or 'COMMIT_OR_PR_TITLE' for a default squash merge commit title. Applicable only if 'allow_squash_merge' is 'true'. +- `template` (Block List, Max: 1) Use a template repository to create this resource. Note on 'internal' visibility with templates: When creating a repository from a template with visibility = 'internal', the provider uses a two-step process due to GitHub API limitations. The template creation API only supports a private boolean parameter. Therefore, repositories with visibility = 'internal' are initially created as private and then immediately updated to internal visibility. This ensures internal repositories are never exposed publicly during creation. (see [below for nested schema](#nestedblock--template)) +- `topics` (Set of String) The list of topics of the repository. Note: This attribute is not compatible with the 'github_repository_topics' resource. Use one of them. 'github_repository_topics' is only meant to be used if the repository itself is not handled via terraform, for example if it's only read as a datasource. +- `visibility` (String) Can be 'public' or 'private'. If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, visibility can also be 'internal'. The visibility parameter overrides the private parameter. +- `vulnerability_alerts` (Boolean, Deprecated) Configure [Dependabot security alerts](https://help.github.com/en/github/managing-security-vulnerabilities/about-security-alerts-for-vulnerable-dependencies) for vulnerable dependencies; set to 'true' to enable, set to 'false' to disable, and leave unset for the default behavior. Configuring this requires that alerts are not being explicitly configured at the organization level. This field will be removed in a future version. Use the 'github_repository_vulnerability_alerts' resource instead. +- `web_commit_signoff_required` (Boolean) Require contributors to sign off on web-based commits. See more in the [GitHub documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-commit-signoff-policy-for-your-repository). -```terraform -resource "github_repository" "forked_repo" { - name = "forked-repository" - description = "This is a fork of another repository" - fork = true - source_owner = "some-org" - source_repo = "original-repository" -} -``` +### Read-Only -## Argument Reference +- `full_name` (String) A string of the form 'orgname/reponame'. +- `git_clone_url` (String) URL that can be provided to 'git clone' to clone the repository anonymously via the git protocol. +- `html_url` (String) URL to the repository on the web. +- `http_clone_url` (String) URL that can be provided to 'git clone' to clone the repository via HTTPS. +- `id` (String) The ID of this resource. +- `node_id` (String) GraphQL global node id for use with v4 API. +- `primary_language` (String) The primary language used in the repository. +- `repo_id` (Number) GitHub ID for the repository. +- `ssh_clone_url` (String) URL that can be provided to 'git clone' to clone the repository via SSH. +- `svn_url` (String) URL that can be provided to 'svn checkout' to check out the repository via GitHub's Subversion protocol emulation. -The following arguments are supported: + +### Nested Schema for `pages` -- `name` - (Required) The name of the repository. +Optional: -- `description` - (Optional) A description of the repository. +- `build_type` (String) The type of GitHub Pages site to build. Can be 'legacy' or 'workflow'. If you use 'legacy' as build type you need to set the option 'source'. +- `cname` (String) The custom domain for the repository. This can only be set after the repository has been created. +- `source` (Block List, Max: 1) The source branch and directory for the rendered Pages site. (see [below for nested schema](#nestedblock--pages--source)) -- `homepage_url` - (Optional) URL of a page describing the project. +Read-Only: -- `fork` - (Optional) Set to `true` to create a fork of an existing repository. When set to `true`, both `source_owner` and `source_repo` must also be specified. +- `custom_404` (Boolean) Whether the rendered GitHub Pages site has a custom 404 page +- `html_url` (String) The absolute URL (including scheme) of the rendered GitHub Pages site e.g. 'https://username.github.io'. +- `status` (String) The GitHub Pages site's build status e.g. building or built. +- `url` (String) The API URL of the rendered GitHub Pages site. -- `source_owner` - (Optional) The GitHub username or organization that owns the repository being forked. Required when `fork` is `true`. + +### Nested Schema for `pages.source` -- `source_repo` - (Optional) The name of the repository to fork. Required when `fork` is `true`. +Required: -- `private` - (Optional) Set to `true` to create a private repository. Repositories are created as public (e.g. open source) by default. +- `branch` (String) The repository branch used to publish the site's source files. (i.e. 'main' or 'gh-pages'). -- `visibility` - (Optional) Can be `public` or `private`. If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, visibility can also be `internal`. The `visibility` parameter overrides the `private` parameter. +Optional: -- `has_issues` - (Optional) Set to `true` to enable the GitHub Issues features on the repository. +- `path` (String) The repository directory from which the site publishes (Default: '/') -- `has_discussions` - (Optional) Set to `true` to enable GitHub Discussions on the repository. Defaults to `false`. -- `has_projects` - (Optional) Set to `true` to enable the GitHub Projects features on the repository. Per the GitHub [documentation](https://developer.github.com/v3/repos/#create) when in an organization that has disabled repository projects it will default to `false` and will otherwise default to `true`. If you specify `true` when it has been disabled it will return an error. -- `has_wiki` - (Optional) Set to `true` to enable the GitHub Wiki features on the repository. + +### Nested Schema for `security_and_analysis` -- `is_template` - (Optional) Set to `true` to tell GitHub that this is a template repository. +Optional: -- `allow_merge_commit` - (Optional) Set to `false` to disable merge commits on the repository. +- `advanced_security` (Block List, Max: 1) The advanced security configuration for the repository. If a repository's visibility is 'public', advanced security is always enabled and cannot be changed, so this setting cannot be supplied. (see [below for nested schema](#nestedblock--security_and_analysis--advanced_security)) +- `code_security` (Block List, Max: 1) The code security configuration for the repository. (see [below for nested schema](#nestedblock--security_and_analysis--code_security)) +- `secret_scanning` (Block List, Max: 1) The secret scanning configuration for the repository. (see [below for nested schema](#nestedblock--security_and_analysis--secret_scanning)) +- `secret_scanning_ai_detection` (Block List, Max: 1) The secret scanning AI detection configuration for this repository. (see [below for nested schema](#nestedblock--security_and_analysis--secret_scanning_ai_detection)) +- `secret_scanning_non_provider_patterns` (Block List, Max: 1) The secret scanning non-provider patterns configuration for this repository. (see [below for nested schema](#nestedblock--security_and_analysis--secret_scanning_non_provider_patterns)) +- `secret_scanning_push_protection` (Block List, Max: 1) The secret scanning push protection configuration for the repository. (see [below for nested schema](#nestedblock--security_and_analysis--secret_scanning_push_protection)) -- `allow_squash_merge` - (Optional) Set to `false` to disable squash merges on the repository. + +### Nested Schema for `security_and_analysis.advanced_security` -- `allow_rebase_merge` - (Optional) Set to `false` to disable rebase merges on the repository. +Required: -- `allow_auto_merge` - (Optional) Set to `true` to allow auto-merging pull requests on the repository. +- `status` (String) Set to 'enabled' to enable advanced security features on the repository. Can be 'enabled' or 'disabled'. -- `allow_forking` - (Optional) Configure private forking for organization owned private and internal repositories; set to `true` to enable, `false` to disable, and leave unset for the default behaviour. Configuring this requires that private forking is not being explicitly configured at the organization level. -- `squash_merge_commit_title` - (Optional) Can be `PR_TITLE` or `COMMIT_OR_PR_TITLE` for a default squash merge commit title. Applicable only if `allow_squash_merge` is `true`. + +### Nested Schema for `security_and_analysis.code_security` -- `squash_merge_commit_message` - (Optional) Can be `PR_BODY`, `COMMIT_MESSAGES`, or `BLANK` for a default squash merge commit message. Applicable only if `allow_squash_merge` is `true`. +Required: -- `merge_commit_title` - Can be `PR_TITLE` or `MERGE_MESSAGE` for a default merge commit title. Applicable only if `allow_merge_commit` is `true`. +- `status` (String) Set to 'enabled' to enable GitHub Code Security on the repository. Can be 'enabled' or 'disabled'. If set to 'enabled', the repository's visibility must be 'public', 'security_and_analysis[0].advanced_security[0].status' must also be set to 'enabled', or your Organization must have split licensing for Advanced security. -- `merge_commit_message` - Can be `PR_BODY`, `PR_TITLE`, or `BLANK` for a default merge commit message. Applicable only if `allow_merge_commit` is `true`. -- `delete_branch_on_merge` - (Optional) Automatically delete head branch after a pull request is merged. Defaults to `false`. + +### Nested Schema for `security_and_analysis.secret_scanning` -- `web_commit_signoff_required` - (Optional) Require contributors to sign off on web-based commits. See more in the [GitHub documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-commit-signoff-policy-for-your-repository). +Required: -- `has_downloads` - (**DEPRECATED**) (Optional) Set to `true` to enable the (deprecated) downloads features on the repository. This attribute is no longer in use, but it hasn't been removed yet. It will be removed in a future version. See [this discussion](https://github.com/orgs/community/discussions/102145#discussioncomment-8351756). +- `status` (String) Set to 'enabled' to enable secret scanning on the repository. Can be 'enabled' or 'disabled'. If set to 'enabled', the repository's visibility must be 'public', 'security_and_analysis[0].advanced_security[0].status' must also be set to 'enabled', or your Organization must have split licensing for Advanced security. -- `auto_init` - (Optional) Set to `true` to produce an initial commit in the repository. -- `gitignore_template` - (Optional) Use the [name of the template](https://github.com/github/gitignore) without the extension. For example, "Haskell". + +### Nested Schema for `security_and_analysis.secret_scanning_ai_detection` -- `license_template` - (Optional) Use the [name of the template](https://github.com/github/choosealicense.com/tree/gh-pages/_licenses) without the extension. For example, "mit" or "mpl-2.0". +Required: -- `default_branch` - (Optional) (Deprecated: Use `github_branch_default` resource instead) The name of the default branch of the repository. **NOTE:** This can only be set after a repository has already been created, and after a correct reference has been created for the target branch inside the repository. This means a user will have to omit this parameter from the initial repository creation and create the target branch inside of the repository prior to setting this attribute. +- `status` (String) Set to 'enabled' to enable secret scanning AI detection on the repository. Can be 'enabled' or 'disabled'. If set to 'enabled', the repository's visibility must be 'public', 'security_and_analysis[0].advanced_security[0].status' must also be set to 'enabled', or your Organization must have split licensing for Advanced security. -- `archived` - (Optional) Specifies if the repository should be archived. Defaults to `false`. **NOTE** Currently, the API does not support unarchiving. -- `archive_on_destroy` - (Optional) Set to `true` to archive the repository instead of deleting on destroy. + +### Nested Schema for `security_and_analysis.secret_scanning_non_provider_patterns` -- `pages` - (Optional) (**DEPRECATED**) The repository's GitHub Pages configuration. Use the `github_repository_pages` resource instead. This field will be removed in a future version. See [GitHub Pages Configuration](#github-pages-configuration) below for details. +Required: -- `security_and_analysis` - (Optional) The repository's [security and analysis](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository) configuration. See [Security and Analysis Configuration](#security-and-analysis-configuration) below for details. +- `status` (String) Set to 'enabled' to enable secret scanning non-provider patterns on the repository. Can be 'enabled' or 'disabled'. If set to 'enabled', the repository's visibility must be 'public', 'security_and_analysis[0].advanced_security[0].status' must also be set to 'enabled', or your Organization must have split licensing for Advanced security. -- `topics` - (Optional) The list of topics of the repository. -~> Note: This attribute is not compatible with the `github_repository_topics` resource. Use one of them. `github_repository_topics` is only meant to be used if the repository itself is not handled via terraform, for example if it's only read as a datasource (see [issue #1845](https://github.com/integrations/terraform-provider-github/issues/1845)). + +### Nested Schema for `security_and_analysis.secret_scanning_push_protection` -- `template` - (Optional) Use a template repository to create this resource. See [Template Repositories](#template-repositories) below for details. +Required: -- `vulnerability_alerts` - (Optional) (**DEPRECATED**) Configure [Dependabot security alerts](https://help.github.com/en/github/managing-security-vulnerabilities/about-security-alerts-for-vulnerable-dependencies) for vulnerable dependencies; set to `true` to enable, set to `false` to disable, and leave unset for the default behavior. Configuring this requires that alerts are not being explicitly configured at the organization level. This field will be removed in a future version. Use the `github_repository_vulnerability_alerts` resource instead. +- `status` (String) Set to 'enabled' to enable secret scanning push protection on the repository. Can be 'enabled' or 'disabled'. If set to 'enabled', the repository's visibility must be 'public', 'security_and_analysis[0].advanced_security[0].status' must also be set to 'enabled', or your Organization must have split licensing for Advanced security. -- `ignore_vulnerability_alerts_during_read` (**DEPRECATED**) (Optional) - This is ignored as the provider now handles lack of permissions automatically. This field will be removed in a future version. -- `allow_update_branch` (Optional) - Set to `true` to always suggest updating pull request branches. -### GitHub Pages Configuration + +### Nested Schema for `template` -The `pages` block supports the following: +Required: -- `source` - (Optional) The source branch and directory for the rendered Pages site. See [GitHub Pages Source](#github-pages-source) below for details. +- `owner` (String) The GitHub organization or user the template repository is owned by. +- `repository` (String) The name of the template repository. -- `build_type` - (Optional) The type of GitHub Pages site to build. Can be `legacy` or `workflow`. If you use `legacy` as build type you need to set the option `source`. +Optional: -- `cname` - (Optional) The custom domain for the repository. This can only be set after the repository has been created. - -#### GitHub Pages Source - -The `source` block supports the following: - -- `branch` - (Required) The repository branch used to publish the site's source files. (i.e. `main` or `gh-pages`. - -- `path` - (Optional) The repository directory from which the site publishes (Default: `/`). - -### Security and Analysis Configuration - -The `security_and_analysis` block supports the following: - -- `advanced_security` - (Optional) The advanced security configuration for the repository. See [Advanced Security Configuration](#advanced-security-configuration) below for details. If a repository's visibility is `public`, advanced security is always enabled and cannot be changed, so this setting cannot be supplied. - -- `code_security` - (Optional) The code security configuration for the repository. See [Code Security](#code-security-configuration) below for details. - -- `secret_scanning` - (Optional) The secret scanning configuration for the repository. See [Secret Scanning Configuration](#secret-scanning-configuration) below for details. - -- `secret_scanning_push_protection` - (Optional) The secret scanning push protection configuration for the repository. See [Secret Scanning Push Protection Configuration](#secret-scanning-push-protection-configuration) below for details. - -- `secret_scanning_ai_detection` - (Optional) The secret scanning ai detection configuration for the repository. See [Secret Scanning AI Detection Configuration](#secret-scanning-ai-detection) below for details. - -- `secret_scanning_non_provider_patterns` - (Optional) The secret scanning non-provider patterns configuration for this repository. See [Secret Scanning Non-Provider Patterns Configuration](#secret-scanning-non-provider-patterns) below for more details. - -#### Advanced Security Configuration - -The `advanced_security` block supports the following: - -- `status` - (Required) Set to `enabled` to enable advanced security features on the repository. Can be `enabled` or `disabled`. - -#### Code Security Configuration - -- `status` - (Required) Set to `enabled` to enable GitHub Code Security on the repository. Can be `enabled` or `disabled`. If set to `enabled`, the repository's visibility must be `public`, `security_and_analysis[0].advanced_security[0].status` must also be set to `enabled`, or your Organization must have split licensing for Advanced security. - -#### Secret Scanning Configuration - -- `status` - (Required) Set to `enabled` to enable secret scanning on the repository. Can be `enabled` or `disabled`. If set to `enabled`, the repository's visibility must be `public`, `security_and_analysis[0].advanced_security[0].status` must also be set to `enabled`, or your Organization must have split licensing for Advanced security. - -#### Secret Scanning Push Protection Configuration - -- `status` - (Required) Set to `enabled` to enable secret scanning push protection on the repository. Can be `enabled` or `disabled`. If set to `enabled`, the repository's visibility must be `public`, `security_and_analysis[0].advanced_security[0].status` must also be set to `enabled`, or your Organization must have split licensing for Advanced security. - -#### Secret Scanning AI Detection - -- `status` - (Required) Set to `enabled` to enable secret scanning AI detection on the repository. Can be `enabled` or `disabled`. If set to `enabled`, the repository's visibility must be `public`, `security_and_analysis[0].advanced_security[0].status` must also be set to `enabled`, or your Organization must have split licensing for Advanced security. - -#### Secret Scanning Non-Provider Patterns - -- `status` - (Required) Set to `enabled` to enable secret scanning non-provider patterns on the repository. Can be `enabled` or `disabled`. If set to `enabled`, the repository's visibility must be `public`, `security_and_analysis[0].advanced_security[0].status` must also be set to `enabled`, or your Organization must have split licensing for Advanced security. - -### Template Repositories - -`template` supports the following arguments: - -- `owner`: The GitHub organization or user the template repository is owned by. -- `repository`: The name of the template repository. -- `include_all_branches`: Whether the new repository should include all the branches from the template repository (defaults to false, which includes only the default branch from the template). - -~> **Note on `internal` visibility with templates**: When creating a repository from a template with `visibility = "internal"`, the provider uses a two-step process due to GitHub API limitations. The template creation API only supports a `private` boolean parameter. Therefore, repositories with `visibility = "internal"` are initially created as private and then immediately updated to internal visibility. This ensures internal repositories are never exposed publicly during creation. - -## Attributes Reference - -The following additional attributes are exported: - -- `full_name` - A string of the form "orgname/reponame". - -- `html_url` - URL to the repository on the web. - -- `ssh_clone_url` - URL that can be provided to `git clone` to clone the repository via SSH. - -- `http_clone_url` - URL that can be provided to `git clone` to clone the repository via HTTPS. - -- `git_clone_url` - URL that can be provided to `git clone` to clone the repository anonymously via the git protocol. - -- `svn_url` - URL that can be provided to `svn checkout` to check out the repository via GitHub's Subversion protocol emulation. - -- `node_id` - GraphQL global node id for use with v4 API - -- `repo_id` - GitHub ID for the repository - -- `primary_language` - The primary language used in the repository. - -- `pages` - The block consisting of the repository's GitHub Pages configuration. - - `custom_404` - Whether the rendered GitHub Pages site has a custom 404 page. - - `html_url` - The absolute URL (including scheme) of the rendered GitHub Pages site e.g. `https://username.github.io`. - - `status` - The GitHub Pages site's build status e.g. `building` or `built`. - -## Import - -Repositories can be imported using the `name`, e.g. - -```shell -terraform import github_repository.terraform myrepo -``` +- `include_all_branches` (Boolean) Whether the new repository should include all the branches from the template repository (defaults to 'false', which includes only the default branch from the template). diff --git a/examples/resources/repository/import.sh b/examples/resources/repository/import.sh new file mode 100644 index 0000000000..6d108e3586 --- /dev/null +++ b/examples/resources/repository/import.sh @@ -0,0 +1 @@ +terraform import github_repository.terraform myrepo diff --git a/github/resource_github_repository.go b/github/resource_github_repository.go index c2117861a4..22b842eb6f 100644 --- a/github/resource_github_repository.go +++ b/github/resource_github_repository.go @@ -22,6 +22,7 @@ func resourceGithubRepository() *schema.Resource { ReadContext: resourceGithubRepositoryRead, UpdateContext: resourceGithubRepositoryUpdate, DeleteContext: resourceGithubRepositoryDelete, + Description: "This resource allows you to create and manage repositories within your GitHub organization or personal account.\n\n~> **Note** When used with GitHub App authentication, even GET requests must have the `contents:write` permission. Without it, the following arguments will be ignored, leading to unexpected behavior and confusing diffs: `allow_merge_commit`, `allow_squash_merge`, `allow_rebase_merge`, `merge_commit_title`, `merge_commit_message`, `squash_merge_commit_title` and `squash_merge_commit_message`.", Importer: &schema.ResourceImporter{ StateContext: resourceGithubRepositoryImport, }, @@ -57,6 +58,7 @@ func resourceGithubRepository() *schema.Resource { Computed: true, // is affected by "visibility" Optional: true, ConflictsWith: []string{"visibility"}, + Description: "Set to 'true' to create a private repository. Repositories are created as public (e.g. open source) by default. Deprecated: use visibility instead.", Deprecated: "use visibility instead", }, "visibility": { @@ -64,7 +66,7 @@ func resourceGithubRepository() *schema.Resource { Optional: true, Computed: true, // is affected by "private" ValidateDiagFunc: validation.ToDiagFunc(validation.StringInSlice([]string{"public", "private", "internal"}, false)), - Description: "Can be 'public' or 'private'. If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, visibility can also be 'internal'.", + Description: "Can be 'public' or 'private'. If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, visibility can also be 'internal'. The visibility parameter overrides the private parameter.", }, // terraform-sdk-provider doesn't properly support tristate booleans: https://github.com/hashicorp/terraform-plugin-sdk/issues/817 // Using TypeString as the best alternative for now. @@ -72,26 +74,26 @@ func resourceGithubRepository() *schema.Resource { Type: schema.TypeString, Optional: true, Computed: true, - Description: "Set to 'true' to fork an existing repository.", + Description: "Set to 'true' to create a fork of an existing repository. When set to 'true', both 'source_owner' and 'source_repo' must also be specified.", }, "source_owner": { Type: schema.TypeString, Optional: true, Computed: true, - Description: "The owner of the source repository to fork from.", + Description: "The GitHub username or organization that owns the repository being forked. Required when 'fork' is 'true'.", }, "source_repo": { Type: schema.TypeString, Optional: true, Computed: true, - Description: "The name of the source repository to fork from.", + Description: "The name of the repository to fork. Required when 'fork' is 'true'.", }, "security_and_analysis": { Type: schema.TypeList, Optional: true, Computed: true, MaxItems: 1, - Description: "Security and analysis settings for the repository. To use this parameter you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository.", + Description: "The repository's [security and analysis](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository) configuration. To use this parameter you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository.", Elem: &schema.Resource{ Schema: map[string]*schema.Schema{ "advanced_security": { @@ -105,7 +107,7 @@ func resourceGithubRepository() *schema.Resource { Type: schema.TypeString, Required: true, ValidateDiagFunc: validation.ToDiagFunc(validation.StringInSlice([]string{"enabled", "disabled"}, false)), - Description: "Set to 'enabled' to enable advanced security features on the repository. Can be 'enabled' or 'disabled', This value being present when split licensing is enabled will error out.", + Description: "Set to 'enabled' to enable advanced security features on the repository. Can be 'enabled' or 'disabled'.", }, }, }, @@ -121,7 +123,7 @@ func resourceGithubRepository() *schema.Resource { Type: schema.TypeString, Required: true, ValidateDiagFunc: validation.ToDiagFunc(validation.StringInSlice([]string{"enabled", "disabled"}, false)), - Description: "Set to 'enabled' to enable code security on the repository. Can be 'enabled' or 'disabled'. If set to 'enabled', the repository's visibility must be 'public', 'security_and_analysis[0].advanced_security[0].status' must also be set to 'enabled', or your Organization must have split licensing for Advanced security.", + Description: "Set to 'enabled' to enable GitHub Code Security on the repository. Can be 'enabled' or 'disabled'. If set to 'enabled', the repository's visibility must be 'public', 'security_and_analysis[0].advanced_security[0].status' must also be set to 'enabled', or your Organization must have split licensing for Advanced security.", }, }, }, @@ -196,7 +198,7 @@ func resourceGithubRepository() *schema.Resource { "has_issues": { Type: schema.TypeBool, Optional: true, - Description: "Set to 'true' to enable the GitHub Issues features on the repository", + Description: "Set to 'true' to enable the GitHub Issues features on the repository.", }, "has_discussions": { Type: schema.TypeBool, @@ -206,7 +208,7 @@ func resourceGithubRepository() *schema.Resource { "has_projects": { Type: schema.TypeBool, Optional: true, - Description: "Set to 'true' to enable the GitHub Projects features on the repository. Per the GitHub documentation when in an organization that has disabled repository projects it will default to 'false' and will otherwise default to 'true'. If you specify 'true' when it has been disabled it will return an error.", + Description: "Set to 'true' to enable the GitHub Projects features on the repository. Per the GitHub [documentation](https://developer.github.com/v3/repos/#create) when in an organization that has disabled repository projects it will default to 'false' and will otherwise default to 'true'. If you specify 'true' when it has been disabled it will return an error.", }, "has_downloads": { Type: schema.TypeBool, @@ -252,31 +254,31 @@ func resourceGithubRepository() *schema.Resource { Type: schema.TypeBool, Optional: true, Computed: true, - Description: "Set to 'true' to allow private forking on the repository; this is only relevant if the repository is owned by an organization and is private or internal.", + Description: "Configure private forking for organization owned private and internal repositories; set to 'true' to enable, 'false' to disable, and leave unset for the default behaviour. Configuring this requires that private forking is not being explicitly configured at the organization level.", }, "squash_merge_commit_title": { Type: schema.TypeString, Optional: true, Default: "COMMIT_OR_PR_TITLE", - Description: "Can be 'PR_TITLE' or 'COMMIT_OR_PR_TITLE' for a default squash merge commit title.", + Description: "Can be 'PR_TITLE' or 'COMMIT_OR_PR_TITLE' for a default squash merge commit title. Applicable only if 'allow_squash_merge' is 'true'.", }, "squash_merge_commit_message": { Type: schema.TypeString, Optional: true, Default: "COMMIT_MESSAGES", - Description: "Can be 'PR_BODY', 'COMMIT_MESSAGES', or 'BLANK' for a default squash merge commit message.", + Description: "Can be 'PR_BODY', 'COMMIT_MESSAGES', or 'BLANK' for a default squash merge commit message. Applicable only if 'allow_squash_merge' is 'true'.", }, "merge_commit_title": { Type: schema.TypeString, Optional: true, Default: "MERGE_MESSAGE", - Description: "Can be 'PR_TITLE' or 'MERGE_MESSAGE' for a default merge commit title.", + Description: "Can be 'PR_TITLE' or 'MERGE_MESSAGE' for a default merge commit title. Applicable only if 'allow_merge_commit' is 'true'.", }, "merge_commit_message": { Type: schema.TypeString, Optional: true, Default: "PR_TITLE", - Description: "Can be 'PR_BODY', 'PR_TITLE', or 'BLANK' for a default merge commit message.", + Description: "Can be 'PR_BODY', 'PR_TITLE', or 'BLANK' for a default merge commit message. Applicable only if 'allow_merge_commit' is 'true'.", }, "delete_branch_on_merge": { Type: schema.TypeBool, @@ -288,7 +290,7 @@ func resourceGithubRepository() *schema.Resource { Type: schema.TypeBool, Optional: true, Computed: true, - Description: "Require contributors to sign off on web-based commits.", + Description: "Require contributors to sign off on web-based commits. See more in the [GitHub documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-commit-signoff-policy-for-your-repository).", }, "auto_init": { Type: schema.TypeBool, @@ -299,7 +301,7 @@ func resourceGithubRepository() *schema.Resource { Type: schema.TypeString, Optional: true, Computed: true, - Description: "Can only be set after initial repository creation, and only if the target branch exists", + Description: "The name of the default branch of the repository. NOTE: This can only be set after a repository has already been created, and after a correct reference has been created for the target branch inside the repository. This means a user will have to omit this parameter from the initial repository creation and create the target branch inside of the repository prior to setting this attribute.", Deprecated: "Use the github_branch_default resource instead", }, "license_template": { @@ -327,7 +329,7 @@ func resourceGithubRepository() *schema.Resource { Type: schema.TypeList, MaxItems: 1, Optional: true, - Description: "The repository's GitHub Pages configuration", + Description: "The repository's GitHub Pages configuration.", Deprecated: "Use the github_repository_pages resource instead. This field will be removed in a future version.", Elem: &schema.Resource{ Schema: map[string]*schema.Schema{ @@ -341,7 +343,7 @@ func resourceGithubRepository() *schema.Resource { "branch": { Type: schema.TypeString, Required: true, - Description: "The repository branch used to publish the site's source files. (i.e. 'main' or 'gh-pages')", + Description: "The repository branch used to publish the site's source files. (i.e. 'main' or 'gh-pages').", }, "path": { Type: schema.TypeString, @@ -356,7 +358,7 @@ func resourceGithubRepository() *schema.Resource { Type: schema.TypeString, Optional: true, Default: "legacy", - Description: "The type the page should be sourced.", + Description: "The type of GitHub Pages site to build. Can be 'legacy' or 'workflow'. If you use 'legacy' as build type you need to set the option 'source'.", ValidateDiagFunc: validateValueFunc([]string{"legacy", "workflow"}), }, "cname": { @@ -372,7 +374,7 @@ func resourceGithubRepository() *schema.Resource { "html_url": { Type: schema.TypeString, Computed: true, - Description: "URL to the repository on the web.", + Description: "The absolute URL (including scheme) of the rendered GitHub Pages site e.g. 'https://username.github.io'.", }, "status": { Type: schema.TypeString, @@ -380,8 +382,9 @@ func resourceGithubRepository() *schema.Resource { Description: "The GitHub Pages site's build status e.g. building or built.", }, "url": { - Type: schema.TypeString, - Computed: true, + Type: schema.TypeString, + Computed: true, + Description: "The API URL of the rendered GitHub Pages site.", }, }, }, @@ -390,7 +393,7 @@ func resourceGithubRepository() *schema.Resource { Type: schema.TypeSet, Optional: true, Computed: true, - Description: "The list of topics of the repository.", + Description: "The list of topics of the repository. Note: This attribute is not compatible with the 'github_repository_topics' resource. Use one of them. 'github_repository_topics' is only meant to be used if the repository itself is not handled via terraform, for example if it's only read as a datasource.", Elem: &schema.Schema{ Type: schema.TypeString, ValidateDiagFunc: validation.ToDiagFunc(validation.StringMatch(regexp.MustCompile(`^[a-z0-9][a-z0-9-]{0,49}$`), "must include only lowercase alphanumeric characters or hyphens and cannot start with a hyphen and consist of 50 characters or less")), @@ -400,14 +403,15 @@ func resourceGithubRepository() *schema.Resource { Type: schema.TypeBool, Optional: true, Computed: true, - Description: "Set to 'true' to enable security alerts for vulnerable dependencies. Enabling requires alerts to be enabled on the owner level. (Note for importing: GitHub enables the alerts on all repos by default). Note that vulnerability alerts have not been successfully tested on any GitHub Enterprise instance and may be unavailable in those settings.", + Description: "Configure [Dependabot security alerts](https://help.github.com/en/github/managing-security-vulnerabilities/about-security-alerts-for-vulnerable-dependencies) for vulnerable dependencies; set to 'true' to enable, set to 'false' to disable, and leave unset for the default behavior. Configuring this requires that alerts are not being explicitly configured at the organization level. This field will be removed in a future version. Use the 'github_repository_vulnerability_alerts' resource instead.", Deprecated: "Use the github_repository_vulnerability_alerts resource instead. This field will be removed in a future version.", }, "ignore_vulnerability_alerts_during_read": { - Type: schema.TypeBool, - Optional: true, - Default: false, - Deprecated: "This is ignored as the provider now handles lack of permissions automatically. This field will be removed in a future version.", + Type: schema.TypeBool, + Optional: true, + Default: false, + Description: "This is ignored as the provider now handles lack of permissions automatically. This field will be removed in a future version.", + Deprecated: "This is ignored as the provider now handles lack of permissions automatically. This field will be removed in a future version.", }, "full_name": { Type: schema.TypeString, @@ -450,14 +454,15 @@ func resourceGithubRepository() *schema.Resource { DiffSuppressOnRefresh: true, }, "primary_language": { - Type: schema.TypeString, - Computed: true, + Type: schema.TypeString, + Computed: true, + Description: "The primary language used in the repository.", }, "template": { Type: schema.TypeList, Optional: true, MaxItems: 1, - Description: "Use a template repository to create this resource.", + Description: "Use a template repository to create this resource. Note on 'internal' visibility with templates: When creating a repository from a template with visibility = 'internal', the provider uses a two-step process due to GitHub API limitations. The template creation API only supports a private boolean parameter. Therefore, repositories with visibility = 'internal' are initially created as private and then immediately updated to internal visibility. This ensures internal repositories are never exposed publicly during creation.", Elem: &schema.Resource{ Schema: map[string]*schema.Schema{ "include_all_branches": { @@ -492,7 +497,7 @@ func resourceGithubRepository() *schema.Resource { "allow_update_branch": { Type: schema.TypeBool, Optional: true, - Description: " Set to 'true' to always suggest updating pull request branches.", + Description: "Set to 'true' to always suggest updating pull request branches.", }, }, CustomizeDiff: customdiff.All( diff --git a/templates/resources/repository.md.tmpl b/templates/resources/repository.md.tmpl index 5b2cd371f2..759f56a64d 100644 --- a/templates/resources/repository.md.tmpl +++ b/templates/resources/repository.md.tmpl @@ -1,206 +1,47 @@ --- page_title: "{{.Name}} ({{.Type}}) - {{.RenderedProviderName}}" +subcategory: "" description: |- - Creates and manages repositories within GitHub organizations or personal accounts +{{ .Description | plainmarkdown | trimspace | prefixlines " " }} --- # {{.Name}} ({{.Type}}) -This resource allows you to create and manage repositories within your GitHub organization or personal account. - -~> **Note** When used with GitHub App authentication, even GET requests must have the `contents:write` permission. Without it, the following arguments will be ignored, leading to unexpected behavior and confusing diffs: `allow_merge_commit`, `allow_squash_merge`, `allow_rebase_merge`, `merge_commit_title`, `merge_commit_message`, `squash_merge_commit_title` and `squash_merge_commit_message`. +{{ .Description | trimspace }} +{{ if .HasExamples -}} ## Example Usage -{{ tffile "examples/resources/repository/example_1.tf" }} - -## Example Usage with Repository Forking - -{{ tffile "examples/resources/repository/example_2.tf" }} - -## Argument Reference - -The following arguments are supported: - -- `name` - (Required) The name of the repository. - -- `description` - (Optional) A description of the repository. - -- `homepage_url` - (Optional) URL of a page describing the project. - -- `fork` - (Optional) Set to `true` to create a fork of an existing repository. When set to `true`, both `source_owner` and `source_repo` must also be specified. - -- `source_owner` - (Optional) The GitHub username or organization that owns the repository being forked. Required when `fork` is `true`. - -- `source_repo` - (Optional) The name of the repository to fork. Required when `fork` is `true`. - -- `private` - (Optional) Set to `true` to create a private repository. Repositories are created as public (e.g. open source) by default. - -- `visibility` - (Optional) Can be `public` or `private`. If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, visibility can also be `internal`. The `visibility` parameter overrides the `private` parameter. - -- `has_issues` - (Optional) Set to `true` to enable the GitHub Issues features on the repository. - -- `has_discussions` - (Optional) Set to `true` to enable GitHub Discussions on the repository. Defaults to `false`. - -- `has_projects` - (Optional) Set to `true` to enable the GitHub Projects features on the repository. Per the GitHub [documentation](https://developer.github.com/v3/repos/#create) when in an organization that has disabled repository projects it will default to `false` and will otherwise default to `true`. If you specify `true` when it has been disabled it will return an error. - -- `has_wiki` - (Optional) Set to `true` to enable the GitHub Wiki features on the repository. - -- `is_template` - (Optional) Set to `true` to tell GitHub that this is a template repository. - -- `allow_merge_commit` - (Optional) Set to `false` to disable merge commits on the repository. - -- `allow_squash_merge` - (Optional) Set to `false` to disable squash merges on the repository. - -- `allow_rebase_merge` - (Optional) Set to `false` to disable rebase merges on the repository. - -- `allow_auto_merge` - (Optional) Set to `true` to allow auto-merging pull requests on the repository. - -- `allow_forking` - (Optional) Configure private forking for organization owned private and internal repositories; set to `true` to enable, `false` to disable, and leave unset for the default behaviour. Configuring this requires that private forking is not being explicitly configured at the organization level. - -- `squash_merge_commit_title` - (Optional) Can be `PR_TITLE` or `COMMIT_OR_PR_TITLE` for a default squash merge commit title. Applicable only if `allow_squash_merge` is `true`. - -- `squash_merge_commit_message` - (Optional) Can be `PR_BODY`, `COMMIT_MESSAGES`, or `BLANK` for a default squash merge commit message. Applicable only if `allow_squash_merge` is `true`. - -- `merge_commit_title` - Can be `PR_TITLE` or `MERGE_MESSAGE` for a default merge commit title. Applicable only if `allow_merge_commit` is `true`. - -- `merge_commit_message` - Can be `PR_BODY`, `PR_TITLE`, or `BLANK` for a default merge commit message. Applicable only if `allow_merge_commit` is `true`. - -- `delete_branch_on_merge` - (Optional) Automatically delete head branch after a pull request is merged. Defaults to `false`. - -- `web_commit_signoff_required` - (Optional) Require contributors to sign off on web-based commits. See more in the [GitHub documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-commit-signoff-policy-for-your-repository). - -- `has_downloads` - (**DEPRECATED**) (Optional) Set to `true` to enable the (deprecated) downloads features on the repository. This attribute is no longer in use, but it hasn't been removed yet. It will be removed in a future version. See [this discussion](https://github.com/orgs/community/discussions/102145#discussioncomment-8351756). - -- `auto_init` - (Optional) Set to `true` to produce an initial commit in the repository. - -- `gitignore_template` - (Optional) Use the [name of the template](https://github.com/github/gitignore) without the extension. For example, "Haskell". - -- `license_template` - (Optional) Use the [name of the template](https://github.com/github/choosealicense.com/tree/gh-pages/_licenses) without the extension. For example, "mit" or "mpl-2.0". - -- `default_branch` - (Optional) (Deprecated: Use `github_branch_default` resource instead) The name of the default branch of the repository. **NOTE:** This can only be set after a repository has already been created, and after a correct reference has been created for the target branch inside the repository. This means a user will have to omit this parameter from the initial repository creation and create the target branch inside of the repository prior to setting this attribute. - -- `archived` - (Optional) Specifies if the repository should be archived. Defaults to `false`. **NOTE** Currently, the API does not support unarchiving. - -- `archive_on_destroy` - (Optional) Set to `true` to archive the repository instead of deleting on destroy. - -- `pages` - (Optional) (**DEPRECATED**) The repository's GitHub Pages configuration. Use the `github_repository_pages` resource instead. This field will be removed in a future version. See [GitHub Pages Configuration](#github-pages-configuration) below for details. - -- `security_and_analysis` - (Optional) The repository's [security and analysis](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository) configuration. See [Security and Analysis Configuration](#security-and-analysis-configuration) below for details. - -- `topics` - (Optional) The list of topics of the repository. - -~> Note: This attribute is not compatible with the `github_repository_topics` resource. Use one of them. `github_repository_topics` is only meant to be used if the repository itself is not handled via terraform, for example if it's only read as a datasource (see [issue #1845](https://github.com/integrations/terraform-provider-github/issues/1845)). - -- `template` - (Optional) Use a template repository to create this resource. See [Template Repositories](#template-repositories) below for details. - -- `vulnerability_alerts` - (Optional) (**DEPRECATED**) Configure [Dependabot security alerts](https://help.github.com/en/github/managing-security-vulnerabilities/about-security-alerts-for-vulnerable-dependencies) for vulnerable dependencies; set to `true` to enable, set to `false` to disable, and leave unset for the default behavior. Configuring this requires that alerts are not being explicitly configured at the organization level. This field will be removed in a future version. Use the `github_repository_vulnerability_alerts` resource instead. +{{- range .ExampleFiles }} -- `ignore_vulnerability_alerts_during_read` (**DEPRECATED**) (Optional) - This is ignored as the provider now handles lack of permissions automatically. This field will be removed in a future version. +{{ tffile . }} +{{- end }} +{{- end }} -- `allow_update_branch` (Optional) - Set to `true` to always suggest updating pull request branches. +{{ .SchemaMarkdown | trimspace }} +{{- if or .HasImport .HasImportIDConfig .HasImportIdentityConfig }} -### GitHub Pages Configuration - -The `pages` block supports the following: - -- `source` - (Optional) The source branch and directory for the rendered Pages site. See [GitHub Pages Source](#github-pages-source) below for details. - -- `build_type` - (Optional) The type of GitHub Pages site to build. Can be `legacy` or `workflow`. If you use `legacy` as build type you need to set the option `source`. - -- `cname` - (Optional) The custom domain for the repository. This can only be set after the repository has been created. - -#### GitHub Pages Source - -The `source` block supports the following: - -- `branch` - (Required) The repository branch used to publish the site's source files. (i.e. `main` or `gh-pages`. - -- `path` - (Optional) The repository directory from which the site publishes (Default: `/`). - -### Security and Analysis Configuration - -The `security_and_analysis` block supports the following: - -- `advanced_security` - (Optional) The advanced security configuration for the repository. See [Advanced Security Configuration](#advanced-security-configuration) below for details. If a repository's visibility is `public`, advanced security is always enabled and cannot be changed, so this setting cannot be supplied. - -- `code_security` - (Optional) The code security configuration for the repository. See [Code Security](#code-security-configuration) below for details. - -- `secret_scanning` - (Optional) The secret scanning configuration for the repository. See [Secret Scanning Configuration](#secret-scanning-configuration) below for details. - -- `secret_scanning_push_protection` - (Optional) The secret scanning push protection configuration for the repository. See [Secret Scanning Push Protection Configuration](#secret-scanning-push-protection-configuration) below for details. - -- `secret_scanning_ai_detection` - (Optional) The secret scanning ai detection configuration for the repository. See [Secret Scanning AI Detection Configuration](#secret-scanning-ai-detection) below for details. - -- `secret_scanning_non_provider_patterns` - (Optional) The secret scanning non-provider patterns configuration for this repository. See [Secret Scanning Non-Provider Patterns Configuration](#secret-scanning-non-provider-patterns) below for more details. - -#### Advanced Security Configuration - -The `advanced_security` block supports the following: - -- `status` - (Required) Set to `enabled` to enable advanced security features on the repository. Can be `enabled` or `disabled`. - -#### Code Security Configuration - -- `status` - (Required) Set to `enabled` to enable GitHub Code Security on the repository. Can be `enabled` or `disabled`. If set to `enabled`, the repository's visibility must be `public`, `security_and_analysis[0].advanced_security[0].status` must also be set to `enabled`, or your Organization must have split licensing for Advanced security. - -#### Secret Scanning Configuration - -- `status` - (Required) Set to `enabled` to enable secret scanning on the repository. Can be `enabled` or `disabled`. If set to `enabled`, the repository's visibility must be `public`, `security_and_analysis[0].advanced_security[0].status` must also be set to `enabled`, or your Organization must have split licensing for Advanced security. - -#### Secret Scanning Push Protection Configuration - -- `status` - (Required) Set to `enabled` to enable secret scanning push protection on the repository. Can be `enabled` or `disabled`. If set to `enabled`, the repository's visibility must be `public`, `security_and_analysis[0].advanced_security[0].status` must also be set to `enabled`, or your Organization must have split licensing for Advanced security. - -#### Secret Scanning AI Detection - -- `status` - (Required) Set to `enabled` to enable secret scanning AI detection on the repository. Can be `enabled` or `disabled`. If set to `enabled`, the repository's visibility must be `public`, `security_and_analysis[0].advanced_security[0].status` must also be set to `enabled`, or your Organization must have split licensing for Advanced security. - -#### Secret Scanning Non-Provider Patterns - -- `status` - (Required) Set to `enabled` to enable secret scanning non-provider patterns on the repository. Can be `enabled` or `disabled`. If set to `enabled`, the repository's visibility must be `public`, `security_and_analysis[0].advanced_security[0].status` must also be set to `enabled`, or your Organization must have split licensing for Advanced security. - -### Template Repositories - -`template` supports the following arguments: - -- `owner`: The GitHub organization or user the template repository is owned by. -- `repository`: The name of the template repository. -- `include_all_branches`: Whether the new repository should include all the branches from the template repository (defaults to false, which includes only the default branch from the template). - -~> **Note on `internal` visibility with templates**: When creating a repository from a template with `visibility = "internal"`, the provider uses a two-step process due to GitHub API limitations. The template creation API only supports a `private` boolean parameter. Therefore, repositories with `visibility = "internal"` are initially created as private and then immediately updated to internal visibility. This ensures internal repositories are never exposed publicly during creation. - -## Attributes Reference - -The following additional attributes are exported: - -- `full_name` - A string of the form "orgname/reponame". - -- `html_url` - URL to the repository on the web. - -- `ssh_clone_url` - URL that can be provided to `git clone` to clone the repository via SSH. - -- `http_clone_url` - URL that can be provided to `git clone` to clone the repository via HTTPS. - -- `git_clone_url` - URL that can be provided to `git clone` to clone the repository anonymously via the git protocol. +## Import -- `svn_url` - URL that can be provided to `svn checkout` to check out the repository via GitHub's Subversion protocol emulation. +Import is supported using the following syntax: +{{- end }} +{{- if .HasImportIdentityConfig }} -- `node_id` - GraphQL global node id for use with v4 API +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: -- `repo_id` - GitHub ID for the repository +{{tffile .ImportIdentityConfigFile }} -- `primary_language` - The primary language used in the repository. +{{ .IdentitySchemaMarkdown | trimspace }} +{{- end }} +{{- if .HasImportIDConfig }} -- `pages` - The block consisting of the repository's GitHub Pages configuration. - - `custom_404` - Whether the rendered GitHub Pages site has a custom 404 page. - - `html_url` - The absolute URL (including scheme) of the rendered GitHub Pages site e.g. `https://username.github.io`. - - `status` - The GitHub Pages site's build status e.g. `building` or `built`. +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 }} -Repositories can be imported using the `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.terraform myrepo -``` +{{codefile "shell" .ImportFile }} +{{- end }} From 4d2f552cbf3e5431b94b3fde82253856fde4ab98 Mon Sep 17 00:00:00 2001 From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Date: Wed, 29 Jul 2026 09:42:43 -0700 Subject: [PATCH 2/3] docs: restore Example Usage and Import sections for github_repository @Copilot flagged that switching the template to tfplugindocs-driven examples dropped both sections from the generated page, since the repo's examples are named example_1.tf / example_2.tf rather than the names .HasExamples looks for. Point tffile and codefile at the actual files in an else branch so both sections render again. docs/resources/repository.md is regenerated output, not hand-edited, so make checkdocs stays green. --- docs/resources/repository.md | 34 ++++++++++++++++++++++++++ templates/resources/repository.md.tmpl | 14 +++++++++++ 2 files changed, 48 insertions(+) diff --git a/docs/resources/repository.md b/docs/resources/repository.md index 01167f6643..759e2a68f1 100644 --- a/docs/resources/repository.md +++ b/docs/resources/repository.md @@ -13,6 +13,32 @@ This resource allows you to create and manage repositories within your GitHub or ~> **Note** When used with GitHub App authentication, even GET requests must have the `contents:write` permission. Without it, the following arguments will be ignored, leading to unexpected behavior and confusing diffs: `allow_merge_commit`, `allow_squash_merge`, `allow_rebase_merge`, `merge_commit_title`, `merge_commit_message`, `squash_merge_commit_title` and `squash_merge_commit_message`. +## Example Usage + +```terraform +resource "github_repository" "example" { + name = "example" + description = "My awesome codebase" + + visibility = "public" + + template { + owner = "github" + repository = "terraform-template-module" + include_all_branches = true + } +} +``` + +```terraform +resource "github_repository" "forked_repo" { + name = "forked-repository" + description = "This is a fork of another repository" + fork = true + source_owner = "some-org" + source_repo = "original-repository" +} +``` ## Schema @@ -176,3 +202,11 @@ Required: Optional: - `include_all_branches` (Boolean) Whether the new repository should include all the branches from the template repository (defaults to 'false', which includes only the default branch from the template). + +## Import + +The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: + +```shell +terraform import github_repository.terraform myrepo +``` diff --git a/templates/resources/repository.md.tmpl b/templates/resources/repository.md.tmpl index 759f56a64d..9d222a4bdc 100644 --- a/templates/resources/repository.md.tmpl +++ b/templates/resources/repository.md.tmpl @@ -16,6 +16,12 @@ description: |- {{ tffile . }} {{- end }} +{{- else }} +## Example Usage + +{{ tffile "examples/resources/repository/example_1.tf" }} + +{{ tffile "examples/resources/repository/example_2.tf" }} {{- end }} {{ .SchemaMarkdown | trimspace }} @@ -45,3 +51,11 @@ The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/c {{codefile "shell" .ImportFile }} {{- end }} +{{- if not (or .HasImport .HasImportIDConfig .HasImportIdentityConfig) }} + +## Import + +The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: + +{{ codefile "shell" "examples/resources/repository/import.sh" }} +{{- end }} From a8ac1597ecf44950db1c870fb8a36254e322c5bf Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 16 Aug 2026 18:47:15 +0000 Subject: [PATCH 3/3] docs: align repository resource template with generic pattern - Rename examples/resources/repository/ to examples/resources/github_repository/ to match tfplugindocs convention (full resource name with provider prefix) - Rename example_*.tf files to resource*.tf to follow tfplugindocs convention - Remove fallback blocks from repository.md.tmpl to match the generic resources.md.tmpl template pattern - Regenerate docs/resources/repository.md with tfplugindocs The repository template now uses .HasExamples/.ExampleFiles and .HasImport/.ImportFile like the generic template, instead of hardcoded fallback paths. Co-authored-by: Matt Van Horn --- docs/resources/repository.md | 3 ++- .../{repository => github_repository}/import.sh | 0 .../example_1.tf => github_repository/resource.tf} | 0 .../resource_forked.tf} | 0 templates/resources/repository.md.tmpl | 14 -------------- 5 files changed, 2 insertions(+), 15 deletions(-) rename examples/resources/{repository => github_repository}/import.sh (100%) rename examples/resources/{repository/example_1.tf => github_repository/resource.tf} (100%) rename examples/resources/{repository/example_2.tf => github_repository/resource_forked.tf} (100%) diff --git a/docs/resources/repository.md b/docs/resources/repository.md index 759e2a68f1..59ff4aed93 100644 --- a/docs/resources/repository.md +++ b/docs/resources/repository.md @@ -12,7 +12,6 @@ This resource allows you to create and manage repositories within your GitHub or ~> **Note** When used with GitHub App authentication, even GET requests must have the `contents:write` permission. Without it, the following arguments will be ignored, leading to unexpected behavior and confusing diffs: `allow_merge_commit`, `allow_squash_merge`, `allow_rebase_merge`, `merge_commit_title`, `merge_commit_message`, `squash_merge_commit_title` and `squash_merge_commit_message`. - ## Example Usage ```terraform @@ -205,6 +204,8 @@ Optional: ## Import +Import is supported using the following syntax: + The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell diff --git a/examples/resources/repository/import.sh b/examples/resources/github_repository/import.sh similarity index 100% rename from examples/resources/repository/import.sh rename to examples/resources/github_repository/import.sh diff --git a/examples/resources/repository/example_1.tf b/examples/resources/github_repository/resource.tf similarity index 100% rename from examples/resources/repository/example_1.tf rename to examples/resources/github_repository/resource.tf diff --git a/examples/resources/repository/example_2.tf b/examples/resources/github_repository/resource_forked.tf similarity index 100% rename from examples/resources/repository/example_2.tf rename to examples/resources/github_repository/resource_forked.tf diff --git a/templates/resources/repository.md.tmpl b/templates/resources/repository.md.tmpl index 9d222a4bdc..759f56a64d 100644 --- a/templates/resources/repository.md.tmpl +++ b/templates/resources/repository.md.tmpl @@ -16,12 +16,6 @@ description: |- {{ tffile . }} {{- end }} -{{- else }} -## Example Usage - -{{ tffile "examples/resources/repository/example_1.tf" }} - -{{ tffile "examples/resources/repository/example_2.tf" }} {{- end }} {{ .SchemaMarkdown | trimspace }} @@ -51,11 +45,3 @@ The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/c {{codefile "shell" .ImportFile }} {{- end }} -{{- if not (or .HasImport .HasImportIDConfig .HasImportIdentityConfig) }} - -## Import - -The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: - -{{ codefile "shell" "examples/resources/repository/import.sh" }} -{{- end }}