docs: mark private attribute as deprecated in github_repository by mvanhorn · Pull Request #3298 · integrations/terraform-provider-github

mvanhorn · 2026-03-23T08:40:39Z

Summary

Marks the private attribute as deprecated in the github_repository resource docs and updates the GitHub Pages example to use visibility instead.

Why this matters

The private attribute triggers a Terraform deprecation warning at plan time ("use visibility instead"), but the docs page doesn't mention this deprecation. Users see the warning with no guidance in the documentation.

The Go source at resource_github_repository.go:60 has Deprecated: "use visibility instead" on the private schema field, but this was never reflected in the markdown docs.

Changes

website/docs/r/repository.html.markdown:

Add (**DEPRECATED**) marker to private attribute description, with "Use visibility instead." guidance
Replace private = false with visibility = "public" in the GitHub Pages example (the first example already uses visibility)

Testing

Verified the change matches the deprecation patterns already used for has_downloads (line 117) and ignore_vulnerability_alerts_during_read (line 145) in the same docs file.

Fixes #3297

This contribution was developed with AI assistance (Claude Code).

github-actions · 2026-03-23T08:40:50Z

👋 Hi! Thank you for this contribution! Just to let you know, our GitHub SDK team does a round of issue and PR reviews twice a week, every Monday and Friday! We have a process in place for prioritizing and responding to your input. Because you are a part of this community please feel free to comment, add to, or pick up any issues/PRs that are labeled with Status: Up for grabs. You & others like you are the reason all of this works! So thank you & happy coding! 🚀

mvanhorn · 2026-04-18T13:36:33Z

@deiga - friendly ping. Approved a while back, no merge activity - let me know if anything else is needed.

deiga · 2026-04-18T15:37:38Z

@mvanhorn your branch has conflicts. Please make sure that you're branch is directly mergeable before requesting work from maintainers.

mvanhorn · 2026-04-18T15:57:33Z

Apologies for the noise. Rebased on main, resolved the conflict, pushed as 1beca71. Should be directly mergeable now.

mvanhorn · 2026-04-19T04:01:32Z

Thanks @deiga — looks like main has moved since you checked. The branch is showing mergeable now (last commit 1beca71 from 2026-03-23). Happy to rebase again if anything has shifted on your end before review.

deiga · 2026-04-19T10:40:54Z

@mvanhorn Please stop pinging people. We will get to your PR when there is capacity for it.
We do see activity notifications without pings.

We really appreciate that you are contributing and value that. At the same time it's important to remember that we are hobby maintainers. It is our free time we use here.

mvanhorn · 2026-04-19T13:50:17Z

Understood, sorry for the noise. I'll leave this one alone - no more pings. Appreciate the maintenance work, this is my last comment on it.

stevehipwell

Thanks for the PR @mvanhorn. We've actually update how the provider docs are generated, so there are currently two (different) ways to rebase and make this change.

The first way, which would be our preference, is to update the schema descriptions to match the documentation, update the examples, and update the template to match the generic resource template pattern.

The second easier way is to just update the examples and template with the desired content.

mvanhorn · 2026-06-04T01:53:02Z

Went with the preferred way. The branch is rebuilt on current main: argument descriptions from the old hand-written template are now schema Description fields (private documents the deprecation and points at visibility), the resource-level Description carries the GitHub App authentication note, templates/resources/repository.md.tmpl now matches the generic resource template pattern, and I added examples/resources/repository/import.sh so the generated Import section renders. docs/resources/repository.md is regenerated via tfplugindocs. go build and gofmt are clean; tfplugindocs validate still reports the pre-existing github_users gap on main, unrelated to this change.

Copilot

Pull request overview

These provider review instructions are being used.

This PR updates the github_repository documentation generation so the private argument’s deprecation (“use visibility instead”) is reflected in the rendered docs, and aligns several schema descriptions with the generated docs.

Changes:

Convert the github_repository docs template to the repo’s tfplugindocs-style rendering (.SchemaMarkdown, .ExampleFiles, import blocks).
Add/update Description text in github/resource_github_repository.go (including explicitly calling out private as deprecated and clarifying visibility precedence).
Add an import snippet and regenerate the rendered docs/resources/repository.md.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
`templates/resources/repository.md.tmpl`	Replaces the hand-written repository docs template with a `tfplugindocs`-driven template (schema/examples/import).
`github/resource_github_repository.go`	Adds resource-level description and expands schema `Description` strings (including `private` deprecation guidance).
`examples/resources/repository/import.sh`	Adds an import command example intended to feed docs generation.
`docs/resources/repository.md`	Updates the rendered docs output for `github_repository` (now schema-driven).


-```terraform
-resource "github_repository" "example" {
-  name        = "example"
-  description = "My awesome codebase"

-  visibility = "public"
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `name` (String) The name of the repository.



mvanhorn · 2026-07-29T17:03:44Z

5e72f53 restores both sections. The template now points tffile and codefile at the actual file names in the repo (example_1.tf, example_2.tf, import.sh) in an else branch, since .HasExamples and .HasImport* look for names this provider does not use.

On the regression you flagged: docs/resources/repository.md here is generated output, not hand-edited. I ran tfplugindocs generate twice and got byte-identical results, and no other doc page drifts, so make checkdocs stays green.

Still worth a maintainer call: you also asked why a docs-only PR touches many schema Description strings in resource_github_repository.go. Those are on the branch from the original scope. Happy to split them into their own PR if you would rather keep this one purely template plus generated docs.

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 integrations#3297 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@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.

- 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 <mvanhorn@users.noreply.github.com>

mvanhorn · 2026-08-16T19:58:52Z

Took the preferred path.

private is marked Deprecated: "use visibility instead" in the schema. Examples now live under examples/resources/github_repository/ (resource.tf, resource_forked.tf, import.sh) so tfplugindocs picks them up. templates/resources/repository.md.tmpl dropped the hardcoded fallbacks and uses the same .HasExamples / .HasImport pattern as the generic template. Regenerated docs show private as (Boolean, Deprecated).

deiga

LGTM!

Copilot

Pull request overview

Copilot reviewed 4 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (5)

github/resource_github_repository.go:69

private is declared with ConflictsWith: []string{"visibility"}, so visibility cannot override it—Terraform rejects configurations that set both. Document this as the replacement for private, not as an override.

				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.",

github/resource_github_repository.go:304

The new schema-generated row only displays (Deprecated) and does not render the Deprecated field's message, so the documented replacement with github_branch_default has been lost. Include that migration guidance in Description so it remains visible in generated docs.

				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.",

github/resource_github_repository.go:332

After switching to SchemaMarkdown, the rendered pages row no longer says to use github_repository_pages; tfplugindocs only emits the deprecated marker, not the Deprecated message. Keep the replacement/removal guidance in Description so users can migrate.

				Description: "The repository's GitHub Pages configuration.",

docs/resources/repository.md:67

This generated row now tells users how to enable downloads but drops the prior warning that the attribute is no longer used and will be removed. Move the deprecation details/link from the schema's Deprecated field into the has_downloads Description, then regenerate this file.

- `has_downloads` (Boolean, Deprecated) Set to 'true' to enable the (deprecated) downloads features on the repository.

templates/resources/repository.md.tmpl:5

The PR description presents this as two targeted documentation edits, but this replaces the full resource template and also migrates examples, import docs, and many schema descriptions. That materially broader scope is not documented and has introduced unrelated documentation changes; either split the tfplugindocs migration from the deprecation fix or update the PR description to explain and validate the expanded scope.

subcategory: ""
description: |-
{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}

deiga · 2026-08-17T21:11:43Z

Pull request overview

Copilot reviewed 4 out of 6 changed files in this pull request and generated no new comments.
Suppressed comments (5)

github/resource_github_repository.go:69

private is declared with ConflictsWith: []string{"visibility"}, so visibility cannot override it—Terraform rejects configurations that set both. Document this as the replacement for private, not as an override.
				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.",
github/resource_github_repository.go:304

The new schema-generated row only displays (Deprecated) and does not render the Deprecated field's message, so the documented replacement with github_branch_default has been lost. Include that migration guidance in Description so it remains visible in generated docs.
				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.",
github/resource_github_repository.go:332

After switching to SchemaMarkdown, the rendered pages row no longer says to use github_repository_pages; tfplugindocs only emits the deprecated marker, not the Deprecated message. Keep the replacement/removal guidance in Description so users can migrate.
				Description: "The repository's GitHub Pages configuration.",
docs/resources/repository.md:67

This generated row now tells users how to enable downloads but drops the prior warning that the attribute is no longer used and will be removed. Move the deprecation details/link from the schema's Deprecated field into the has_downloads Description, then regenerate this file.
- `has_downloads` (Boolean, Deprecated) Set to 'true' to enable the (deprecated) downloads features on the repository.
templates/resources/repository.md.tmpl:5

The PR description presents this as two targeted documentation edits, but this replaces the full resource template and also migrates examples, import docs, and many schema descriptions. That materially broader scope is not documented and has introduced unrelated documentation changes; either split the tfplugindocs migration from the deprecation fix or update the PR description to explain and validate the expanded scope.
subcategory: ""
description: |-
{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}

@mvanhorn Please check these comments out. There might have been some information lost in the docs

stevehipwell

Please add import-by-string-id.tf to the examples and use the format resource_N.tf (e.g. resource_1.tf & resource_2.tf) for the example resources adding in a comment to explain the purpose.

stevehipwell · 2026-08-18T11:06:39Z

 		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`.",


Please use the pattern "Resource to ..." for the description and keep it short. Additional content can be added directly to the template. Please also follow the resource structure guidance in ARCHITECTURE.md for where this should be placed.

github-actions Bot added the Type: Documentation Improvements or additions to documentation label Mar 23, 2026

deiga previously approved these changes Mar 23, 2026

View reviewed changes

deiga requested a review from stevehipwell March 23, 2026 11:19

mvanhorn dismissed deiga’s stale review via 1beca71 April 18, 2026 15:56

mvanhorn force-pushed the docs/3297-repository-deprecated-attrs branch from 94976ac to 1beca71 Compare April 18, 2026 15:56

deiga previously approved these changes Apr 18, 2026

View reviewed changes

deiga added this to the v6.13.0 milestone Apr 18, 2026

stevehipwell requested changes May 15, 2026

View reviewed changes

deiga added the Awaiting response label Jun 3, 2026

deiga removed this from the v6.13.0 milestone Jun 3, 2026

mvanhorn dismissed deiga’s stale review via 24ef86e June 4, 2026 01:52

mvanhorn force-pushed the docs/3297-repository-deprecated-attrs branch from 1beca71 to 24ef86e Compare June 4, 2026 01:52

deiga requested a review from Copilot June 4, 2026 03:49

Copilot started reviewing on behalf of deiga June 4, 2026 03:49 View session

Copilot AI reviewed Jun 4, 2026

View reviewed changes

mvanhorn and others added 3 commits August 16, 2026 18:41

cursor Bot force-pushed the docs/3297-repository-deprecated-attrs branch from 5e72f53 to a8ac159 Compare August 16, 2026 18:47

deiga requested a balanced review from Copilot August 16, 2026 21:45

Copilot started reviewing on behalf of deiga August 16, 2026 21:46 View session

deiga approved these changes Aug 16, 2026

View reviewed changes

deiga requested a review from stevehipwell August 16, 2026 21:47

Copilot AI reviewed Aug 16, 2026

View reviewed changes

stevehipwell reviewed Aug 18, 2026

View reviewed changes

Uh oh!

Conversation

mvanhorn commented Mar 23, 2026

Summary

Why this matters

Changes

Testing

Uh oh!

github-actions Bot commented Mar 23, 2026

Uh oh!

mvanhorn commented Apr 18, 2026

Uh oh!

deiga commented Apr 18, 2026

Uh oh!

mvanhorn commented Apr 18, 2026

Uh oh!

mvanhorn commented Apr 19, 2026

Uh oh!

deiga commented Apr 19, 2026

Uh oh!

mvanhorn commented Apr 19, 2026

Uh oh!

stevehipwell left a comment

Choose a reason for hiding this comment

Uh oh!

mvanhorn commented Jun 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mvanhorn commented Jul 29, 2026

Uh oh!

mvanhorn commented Aug 16, 2026

Uh oh!

deiga left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

deiga commented Aug 17, 2026

Pull request overview

Uh oh!

stevehipwell left a comment

Choose a reason for hiding this comment

Uh oh!

stevehipwell Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants