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