diff --git a/docs/resources/repository_webhook.md b/docs/resources/repository_webhook.md index 3b85b418ec..38faf3aa21 100644 --- a/docs/resources/repository_webhook.md +++ b/docs/resources/repository_webhook.md @@ -1,7 +1,8 @@ --- page_title: "github_repository_webhook (Resource) - GitHub" +subcategory: "" description: |- - Creates and manages repository webhooks within GitHub organizations or personal accounts + This resource allows you to create and manage webhooks for repositories within your GitHub organization or personal account. --- # github_repository_webhook (Resource) @@ -13,16 +14,16 @@ This resource allows you to create and manage webhooks for repositories within y ## Example Usage ```terraform -resource "github_repository" "repo" { - name = "foo" +resource "github_repository" "example_repo" { + name = "example-repo" description = "Terraform acceptance tests" homepage_url = "http://example.com/" visibility = "public" } -resource "github_repository_webhook" "foo" { - repository = github_repository.repo.name +resource "github_repository_webhook" "example_webhook" { + repository = github_repository.example_repo.name configuration { url = "https://google.de/" @@ -36,42 +37,57 @@ resource "github_repository_webhook" "foo" { } ``` -## Argument Reference + +## Schema -The following arguments are supported: +### Required -- `repository` - (Required) The repository of the webhook. +- `events` (Set of String) A list of events which should trigger the webhook. See a list of [available events](https://developer.github.com/v3/activity/events/types/). +- `repository` (String) The repository name of the webhook, not including the organization, which will be inferred. -- `events` - (Required) A list of events which should trigger the webhook. See a list of [available events](https://developer.github.com/v3/activity/events/types/). +### Optional -- `configuration` - (Required) Configuration block for the webhook. [Detailed below.](#configuration) +- `active` (Boolean) Indicate if the webhook should receive events. Defaults to 'true'. +- `configuration` (Block List, Max: 1) Configuration for the webhook. (see [below for nested schema](#nestedblock--configuration)) +- `etag` (String) An etag representing the webhook object. -- `active` - (Optional) Indicate if the webhook should receive events. Defaults to `true`. +### Read-Only -### configuration +- `id` (String) The ID of this resource. +- `url` (String) Configuration block for the webhook. -- `url` - (Required) The URL of the webhook. + +### Nested Schema for `configuration` -- `content_type` - (Required) The content type for the payload. Valid values are either `form` or `json`. +Required: -- `secret` - (Optional) The shared secret for the webhook. [See API documentation](https://developer.github.com/v3/repos/hooks/#create-a-hook). +- `url` (String, Sensitive) The URL of the webhook. -- `insecure_ssl` - (Optional) Insecure SSL boolean toggle. Defaults to `false`. +Optional: -## Attributes Reference +- `content_type` (String) The content type for the payload. Valid values are either 'form' or 'json'. +- `insecure_ssl` (Boolean) Insecure SSL boolean toggle. Defaults to 'false'. +- `secret` (String, Sensitive) The shared secret for the webhook. [See API documentation](https://developer.github.com/v3/repos/hooks/#create-a-hook). -The following additional attributes are exported: +## Import -- `url` - URL of the webhook. This is a sensitive attribute because it may include basic auth credentials. +Import is supported using the following syntax: -## Import +Repository webhooks can be imported using the `name` of the repository, combined with the `id` of the webhook, separated by a `/` character. The `id` of the webhook can be found in the URL of the webhook. For example: `"https://github.com/example-org/example-repo/settings/hooks/123456789"`, where `123456789` is the `id` of the webhook. + +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: -Repository webhooks can be imported using the `name` of the repository, combined with the `id` of the webhook, separated by a `/` character. The `id` of the webhook can be found in the URL of the webhook. For example: `"https://github.com/foo-org/foo-repo/settings/hooks/14711452"`. +```terraform +import { + to = github_repository_webhook.example_webhook + id = "example-repo/123456789" +} +``` -Importing uses the name of the repository, as well as the ID of the webhook, e.g. +The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell -terraform import github_repository_webhook.terraform terraform/11235813 +terraform import github_repository_webhook.example_webhook example-repo/123456789 ``` If secret is populated in the webhook's configuration, the value will be imported as "********". diff --git a/examples/resources/github_repository_webhook/import-by-string-id.tf b/examples/resources/github_repository_webhook/import-by-string-id.tf new file mode 100644 index 0000000000..c1466812a0 --- /dev/null +++ b/examples/resources/github_repository_webhook/import-by-string-id.tf @@ -0,0 +1,4 @@ +import { + to = github_repository_webhook.example_webhook + id = "example-repo/123456789" +} diff --git a/examples/resources/github_repository_webhook/import.sh b/examples/resources/github_repository_webhook/import.sh new file mode 100644 index 0000000000..08416a4636 --- /dev/null +++ b/examples/resources/github_repository_webhook/import.sh @@ -0,0 +1 @@ +terraform import github_repository_webhook.example_webhook example-repo/123456789 diff --git a/examples/resources/repository_webhook/example_1.tf b/examples/resources/github_repository_webhook/resource-1.tf similarity index 59% rename from examples/resources/repository_webhook/example_1.tf rename to examples/resources/github_repository_webhook/resource-1.tf index 07ce862c9e..31619327ae 100644 --- a/examples/resources/repository_webhook/example_1.tf +++ b/examples/resources/github_repository_webhook/resource-1.tf @@ -1,13 +1,13 @@ -resource "github_repository" "repo" { - name = "foo" +resource "github_repository" "example_repo" { + name = "example-repo" description = "Terraform acceptance tests" homepage_url = "http://example.com/" visibility = "public" } -resource "github_repository_webhook" "foo" { - repository = github_repository.repo.name +resource "github_repository_webhook" "example_webhook" { + repository = github_repository.example_repo.name configuration { url = "https://google.de/" diff --git a/github/resource_github_repository_webhook.go b/github/resource_github_repository_webhook.go index 69d8443d04..9d917540a1 100644 --- a/github/resource_github_repository_webhook.go +++ b/github/resource_github_repository_webhook.go @@ -16,6 +16,7 @@ import ( func resourceGithubRepositoryWebhook() *schema.Resource { return &schema.Resource{ + Description: "This resource allows you to create and manage webhooks for repositories within your GitHub organization or personal account.", CreateContext: resourceGithubRepositoryWebhookCreate, ReadContext: resourceGithubRepositoryWebhookRead, UpdateContext: resourceGithubRepositoryWebhookUpdate, @@ -55,13 +56,13 @@ func resourceGithubRepositoryWebhook() *schema.Resource { Required: true, Elem: &schema.Schema{Type: schema.TypeString}, Set: schema.HashString, - Description: "A list of events which should trigger the webhook", + Description: "A list of events which should trigger the webhook. See a list of [available events](https://developer.github.com/v3/activity/events/types/).", }, "configuration": webhookConfigurationSchema(), "url": { Type: schema.TypeString, Computed: true, - Description: "Configuration block for the webhook", + Description: "Configuration block for the webhook.", }, "active": { Type: schema.TypeBool, @@ -70,9 +71,10 @@ func resourceGithubRepositoryWebhook() *schema.Resource { Description: "Indicate if the webhook should receive events. Defaults to 'true'.", }, "etag": { - Type: schema.TypeString, - Optional: true, - Computed: true, + Type: schema.TypeString, + Optional: true, + Computed: true, + Description: "An etag representing the webhook object.", DiffSuppressFunc: func(k, o, n string, d *schema.ResourceData) bool { return true }, diff --git a/github/schema_webhook_configuration.go b/github/schema_webhook_configuration.go index bc0162b715..df0a6eb22f 100644 --- a/github/schema_webhook_configuration.go +++ b/github/schema_webhook_configuration.go @@ -27,7 +27,7 @@ func webhookConfigurationSchema() *schema.Schema { Type: schema.TypeString, Optional: true, Sensitive: true, - Description: "The shared secret for the webhook", + Description: "The shared secret for the webhook. [See API documentation](https://developer.github.com/v3/repos/hooks/#create-a-hook).", }, "insecure_ssl": { Type: schema.TypeBool, diff --git a/templates/resources/repository_webhook.md.tmpl b/templates/resources/repository_webhook.md.tmpl index e0ffdc111f..a67b0a5a68 100644 --- a/templates/resources/repository_webhook.md.tmpl +++ b/templates/resources/repository_webhook.md.tmpl @@ -1,55 +1,44 @@ --- page_title: "{{.Name}} ({{.Type}}) - {{.RenderedProviderName}}" +subcategory: "" description: |- - Creates and manages repository webhooks within GitHub organizations or personal accounts +{{ .Description | plainmarkdown | trimspace | prefixlines " " }} --- # {{.Name}} ({{.Type}}) -This resource allows you to create and manage webhooks for repositories within your GitHub organization or personal account. +{{ .Description | trimspace }} ~> **Note on Archived Repositories**: When a repository is archived, GitHub makes it read-only, preventing webhook 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. -## Example Usage - -{{ tffile "examples/resources/repository_webhook/example_1.tf" }} - -## Argument Reference - -The following arguments are supported: - -- `repository` - (Required) The repository of the webhook. - -- `events` - (Required) A list of events which should trigger the webhook. See a list of [available events](https://developer.github.com/v3/activity/events/types/). - -- `configuration` - (Required) Configuration block for the webhook. [Detailed below.](#configuration) +{{- if .HasExamples }} -- `active` - (Optional) Indicate if the webhook should receive events. Defaults to `true`. - -### configuration - -- `url` - (Required) The URL of the webhook. - -- `content_type` - (Required) The content type for the payload. Valid values are either `form` or `json`. - -- `secret` - (Optional) The shared secret for the webhook. [See API documentation](https://developer.github.com/v3/repos/hooks/#create-a-hook). +## Example Usage +{{ range .ExampleFiles }} +{{ tffile . }} +{{- end }} +{{- end }} -- `insecure_ssl` - (Optional) Insecure SSL boolean toggle. Defaults to `false`. +{{ .SchemaMarkdown | trimspace }} +{{- if or .HasImport .HasImportIDConfig }} -## Attributes Reference +## Import -The following additional attributes are exported: +Import is supported using the following syntax: +{{- end }} +{{- if .HasImportIDConfig }} -- `url` - URL of the webhook. This is a sensitive attribute because it may include basic auth credentials. +Repository webhooks can be imported using the `name` of the repository, combined with the `id` of the webhook, separated by a `/` character. The `id` of the webhook can be found in the URL of the webhook. For example: `"https://github.com/example-org/example-repo/settings/hooks/123456789"`, where `123456789` is the `id` of the webhook. -## Import +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: -Repository webhooks can be imported using the `name` of the repository, combined with the `id` of the webhook, separated by a `/` character. The `id` of the webhook can be found in the URL of the webhook. For example: `"https://github.com/foo-org/foo-repo/settings/hooks/14711452"`. +{{tffile .ImportIDConfigFile }} +{{- end }} +{{- if .HasImport }} -Importing uses the name of the repository, as well as the ID of the webhook, e.g. +The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: -```shell -terraform import github_repository_webhook.terraform terraform/11235813 -``` +{{codefile "shell" .ImportFile }} If secret is populated in the webhook's configuration, the value will be imported as "********". +{{- end }}