diff --git a/modules/gh-org-webhook/.terraform-docs.yml b/modules/gh-org-webhook/.terraform-docs.yml new file mode 100644 index 000000000..49be8b854 --- /dev/null +++ b/modules/gh-org-webhook/.terraform-docs.yml @@ -0,0 +1,48 @@ +formatter: "markdown" # this is required + +version: "" + +header-from: docs/header.md +footer-from: docs/footer.md + +recursive: + enabled: false + path: modules + include-main: true + +sections: + hide: [] + show: [] + +content: "" + +output: + file: "README.md" + mode: inject + template: |- + + {{ .Content }} + + +output-values: + enabled: false + from: "" + +sort: + enabled: true + by: name + +settings: + anchor: true + color: true + default: true + description: false + escape: true + hide-empty: false + html: true + indent: 2 + lockfile: true + read-comments: true + required: true + sensitive: true + type: true diff --git a/modules/gh-org-webhook/README.md b/modules/gh-org-webhook/README.md new file mode 100644 index 000000000..43d5b6075 --- /dev/null +++ b/modules/gh-org-webhook/README.md @@ -0,0 +1,143 @@ + +# **GitHub Organization Webhook Terraform Module** + +## Overview + +This module creates and manages a GitHub **organization-level webhook** using a single strongly-typed `config` object. + +It is designed for Prefapp’s Internal Developer Platform and automated webhook provisioning pipelines. The module accepts input directly from external programs via JSON. + +## Key Features + +- **Single config object**: All webhook settings in one `config` variable +- **Full event support**: Subscribe to any GitHub organization webhook event +- **Secure by default**: Supports secret, content type, and SSL validation +- **JSON-native**: Perfect for programmatic generation +- **Strong validation**: Ensures only valid events and required fields + +## Supported Events + +The module supports **all standard GitHub organization webhook events**. + +Common events include: + +- `push` +- `pull_request` +- `issues` +- `workflow_run` +- `workflow_dispatch` +- `release` +- `create` +- `delete` +- `fork` +- `member` +- `public` +- `repository` +- `status` +- `watch` +- `commit_comment` +- `gollum` +- `team_add` +- `team` +- `organization` +- `project` +- `project_card` +- `project_column` +- `milestone` +- `deployment` +- `deployment_status` +- `discussion` +- `discussion_comment` + +For the **complete and up-to-date list** of all available webhook events and their payloads, see the official GitHub documentation: + +→ **[Webhook events and payloads](https://docs.github.com/en/webhooks/webhook-events-and-payloads)** + +## Basic Usage + +### Using `terraform.tfvars.json` (recommended) + +```hcl +module "org_webhook" { + source = "git::https://github.com/prefapp/tfm.git//modules/gh-org-webhook" + + config = var.config +} + +### Inline example + +```hcl +module "org\_webhook" { + source = "git::https://github.com/prefapp/tfm.git//modules/gh-org-webhook" + + config = { + webhook = { + active = true + events = ["push", "pull\_request", "issues", "workflow\_run"] + configuration = { + url = "https://example.com/webhook" + contentType = "json" + secret = "secret-xxx" + insecureSsl = false + } + } + } +} +``` +``` + +## Requirements + +| Name | Version | +|------|---------| +| [github](#requirement\_github) | ~> 6.0 | + +## Providers + +| Name | Version | +|------|---------| +| [github](#provider\_github) | ~> 6.0 | + +## Modules + +No modules. + +## Resources + +| Name | Type | +|------|------| +| [github_organization_webhook.this](https://registry.terraform.io/providers/integrations/github/latest/docs/resources/organization_webhook) | resource | + +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|------|---------|:--------:| +| [config](#input\_config) | GitHub organization webhook configuration |
object({
webhook = object({
active = optional(bool, true)
events = list(string)

configuration = object({
url = string
contentType = optional(string, "json")
secret = optional(string)
insecureSsl = optional(bool, false)
})
})
})
| n/a | yes | + +## Outputs + +| Name | Description | +|------|-------------| +| [active](#output\_active) | Whether the webhook is active | +| [events](#output\_events) | Events the webhook is subscribed to | +| [webhook\_id](#output\_webhook\_id) | ID of the created organization webhook | +| [webhook\_url](#output\_webhook\_url) | URL of the webhook | + +### `docs/footer.md` +```markdown +## Examples + +For detailed examples, refer to the [module examples](https://github.com/prefapp/tfm/tree/main/modules/gh-org-webhook/_examples): + +- [basic](https://github.com/prefapp/tfm/tree/main/modules/gh-org-webhook/_examples/basic) - Organization webhook with push/pull_request/issues + +## Resources + +- **github_organization_webhook**: [Official Documentation](https://registry.terraform.io/providers/integrations/github/latest/docs/resources/organization_webhook) +- **GitHub Terraform Provider**: [Official Documentation](https://registry.terraform.io/providers/integrations/github/latest/docs) + +## Support + +For issues, questions, or contributions related to this module, please visit the [repository's issue tracker](https://github.com/prefapp/tfm/issues). +``` + \ No newline at end of file diff --git a/modules/gh-org-webhook/_examples/basic/config.json b/modules/gh-org-webhook/_examples/basic/config.json new file mode 100644 index 000000000..5f7ef2921 --- /dev/null +++ b/modules/gh-org-webhook/_examples/basic/config.json @@ -0,0 +1,18 @@ +{ + "config": { + "webhook": { + "active": true, + "events": [ + "push", + "pull_request", + "issues" + ], + "configuration": { + "url": "https://example.com/webhook", + "contentType": "json", + "secret": "secret-xxx", + "insecureSsl": false + } + } + } +} diff --git a/modules/gh-org-webhook/_examples/basic/main.tf b/modules/gh-org-webhook/_examples/basic/main.tf new file mode 100644 index 000000000..9fa9f08d7 --- /dev/null +++ b/modules/gh-org-webhook/_examples/basic/main.tf @@ -0,0 +1,18 @@ +terraform { + required_providers { + github = { + source = "integrations/github" + version = "~> 6.0" + } + } +} + +module "org_webhook" { + source = "../../" + + config = jsondecode(file("${path.module}/config.json")).config +} + +output "webhook_id" { + value = module.org_webhook.webhook_id +} diff --git a/modules/gh-org-webhook/docs/footer.md b/modules/gh-org-webhook/docs/footer.md new file mode 100644 index 000000000..cb0d8f54c --- /dev/null +++ b/modules/gh-org-webhook/docs/footer.md @@ -0,0 +1,16 @@ +### `docs/footer.md` +```markdown +## Examples + +For detailed examples, refer to the [module examples](https://github.com/prefapp/tfm/tree/main/modules/gh-org-webhook/_examples): + +- [basic](https://github.com/prefapp/tfm/tree/main/modules/gh-org-webhook/_examples/basic) - Organization webhook with push/pull_request/issues + +## Resources + +- **github_organization_webhook**: [Official Documentation](https://registry.terraform.io/providers/integrations/github/latest/docs/resources/organization_webhook) +- **GitHub Terraform Provider**: [Official Documentation](https://registry.terraform.io/providers/integrations/github/latest/docs) + +## Support + +For issues, questions, or contributions related to this module, please visit the [repository's issue tracker](https://github.com/prefapp/tfm/issues). diff --git a/modules/gh-org-webhook/docs/header.md b/modules/gh-org-webhook/docs/header.md new file mode 100644 index 000000000..7b304b79a --- /dev/null +++ b/modules/gh-org-webhook/docs/header.md @@ -0,0 +1,85 @@ +# **GitHub Organization Webhook Terraform Module** + +## Overview + +This module creates and manages a GitHub **organization-level webhook** using a single strongly-typed `config` object. + +It is designed for Prefapp’s Internal Developer Platform and automated webhook provisioning pipelines. The module accepts input directly from external programs via JSON. + +## Key Features + +- **Single config object**: All webhook settings in one `config` variable +- **Full event support**: Subscribe to any GitHub organization webhook event +- **Secure by default**: Supports secret, content type, and SSL validation +- **JSON-native**: Perfect for programmatic generation +- **Strong validation**: Ensures only valid events and required fields + +## Supported Events + +The module supports **all standard GitHub organization webhook events**. + +Common events include: + +- `push` +- `pull_request` +- `issues` +- `workflow_run` +- `workflow_dispatch` +- `release` +- `create` +- `delete` +- `fork` +- `member` +- `public` +- `repository` +- `status` +- `watch` +- `commit_comment` +- `gollum` +- `team_add` +- `team` +- `organization` +- `project` +- `project_card` +- `project_column` +- `milestone` +- `deployment` +- `deployment_status` +- `discussion` +- `discussion_comment` + +For the **complete and up-to-date list** of all available webhook events and their payloads, see the official GitHub documentation: + +→ **[Webhook events and payloads](https://docs.github.com/en/webhooks/webhook-events-and-payloads)** + +## Basic Usage + +### Using `terraform.tfvars.json` (recommended) + +```hcl +module "org_webhook" { + source = "git::https://github.com/prefapp/tfm.git//modules/gh-org-webhook" + + config = var.config +} + +### Inline example + +```hcl +module "org_webhook" { + source = "git::https://github.com/prefapp/tfm.git//modules/gh-org-webhook" + + config = { + webhook = { + active = true + events = ["push", "pull_request", "issues", "workflow_run"] + configuration = { + url = "https://example.com/webhook" + contentType = "json" + secret = "secret-xxx" + insecureSsl = false + } + } + } +} +``` diff --git a/modules/gh-org-webhook/main.tf b/modules/gh-org-webhook/main.tf new file mode 100644 index 000000000..d87ef273c --- /dev/null +++ b/modules/gh-org-webhook/main.tf @@ -0,0 +1,11 @@ +resource "github_organization_webhook" "this" { + active = var.config.webhook.active + events = var.config.webhook.events + + configuration { + url = var.config.webhook.configuration.url + content_type = var.config.webhook.configuration.contentType + secret = var.config.webhook.configuration.secret + insecure_ssl = var.config.webhook.configuration.insecureSsl + } +} diff --git a/modules/gh-org-webhook/outputs.tf b/modules/gh-org-webhook/outputs.tf new file mode 100644 index 000000000..60949e28e --- /dev/null +++ b/modules/gh-org-webhook/outputs.tf @@ -0,0 +1,19 @@ +output "webhook_id" { + description = "ID of the created organization webhook" + value = github_organization_webhook.this.id +} + +output "webhook_url" { + description = "URL of the webhook" + value = github_organization_webhook.this.configuration[0].url +} + +output "active" { + description = "Whether the webhook is active" + value = github_organization_webhook.this.active +} + +output "events" { + description = "Events the webhook is subscribed to" + value = github_organization_webhook.this.events +} diff --git a/modules/gh-org-webhook/variables.tf b/modules/gh-org-webhook/variables.tf new file mode 100644 index 000000000..6fed02636 --- /dev/null +++ b/modules/gh-org-webhook/variables.tf @@ -0,0 +1,28 @@ +variable "config" { + description = "GitHub organization webhook configuration" + type = object({ + webhook = object({ + active = optional(bool, true) + events = list(string) + + configuration = object({ + url = string + contentType = optional(string, "json") + secret = optional(string) + insecureSsl = optional(bool, false) + }) + }) + }) + + validation { + condition = length(var.config.webhook.events) > 0 + error_message = "At least one event must be defined in webhook.events." + } + + validation { + condition = alltrue([ + for e in var.config.webhook.events : contains(["push", "pull_request", "issues", "commit_comment", "create", "delete", "fork", "gollum", "member", "public", "release", "status", "watch", "workflow_dispatch"], e) + ]) + error_message = "Invalid event type in webhook.events." + } +} diff --git a/modules/gh-org-webhook/versions.tf b/modules/gh-org-webhook/versions.tf new file mode 100644 index 000000000..30369f8ed --- /dev/null +++ b/modules/gh-org-webhook/versions.tf @@ -0,0 +1,9 @@ +terraform { + required_providers { + github = { + source = "integrations/github" + version = "~> 6.0" + } + } +} + diff --git a/release-please-config.json b/release-please-config.json index 1791e861c..1a513dbe6 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -151,6 +151,9 @@ "modules/aws-secretsmanager-replication": { "package-name": "aws-secretsmanager-replication" }, + "modules/gh-org-webhook": { + "package-name": "gh-org-webhook" + }, "modules/azure-vnet-gateway": { "package-name": "azure-vnet-gateway" },