feat: Add support for org-level runners

[bdeshi]

this PR adds support for org-level webhooks and runners.

added a new optional input source_organization.
if source_location is set to the special string CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION, then webhooks are created for the github org named by source_organization.

[baolsen]

Thanks for the contribution!

CI is failing due to code formatting / terraform docs.
It can be fixed automatically using pre-commit run -a

[baolsen]

Hey @bdeshi , wondering if you would be able to fixup this one so we can get it merged in

[bdeshi]

@baolsen sorry about the longterm radio silence. i'll update my branch with fixes asap.

[bdeshi]

@baolsen fixes committed. please review at your convenience.

[baolsen]

Changes look good to me.
I've asked Copilot to review as well, just out of interest.

[Copilot]

Pull request overview

This PR adds support for organization-level GitHub runners by introducing a new webhook scope configuration mechanism. When using the special value CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION for source_location, the module now creates organization-level webhooks instead of repository-specific ones.

Key Changes:

• Added new optional variable source_organization to specify the GitHub organization name for org-level webhooks
• Updated source_location validation to accept the special value CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION
• Added dynamic scope_configuration block to the webhook resource for organization-level setup
• Created new example basic-org demonstrating the org-level runner configuration

Reviewed changes

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

Show a summary per file

File	Description
variables.tf	Adds source_organization variable and updates source_location validation to support org-level webhooks
main.tf	Implements dynamic scope_configuration block to enable organization-level webhook creation
examples/basic-org/terraform.tf	Defines Terraform and provider version requirements for the new org-level example
examples/basic-org/providers.tf	Configures AWS provider for the example
examples/basic-org/main.tf	Demonstrates org-level runner configuration using the new variables
examples/basic-org/README.md	Auto-generated documentation for the org-level example
docs/org_level_runners.md	Provides usage documentation for setting up organization-level runners
README.md	Updates module documentation with the new source_organization input variable

[Copilot]

The name attribute in the scope_configuration block should have validation to ensure var.source_organization is not null. While the dynamic block only creates the scope_configuration when source_location equals the special value, there's no guarantee that source_organization is set. This could result in a Terraform error at apply time.

Consider adding a precondition or using a more defensive approach:

dynamic "scope_configuration" {
  for_each = var.source_location == "CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION" && var.source_organization != null ? toset([1]) : toset([])
  content {
    name  = var.source_organization
    scope = "GITHUB_ORGANIZATION"
  }
}

However, this is a workaround. The proper fix is to add validation to the source_organization variable (see comment on variables.tf).

[baolsen]

@bdeshi , what do you think of adding this rule?

Cross-parameter validation is only available from Terraform 1.9 so we cannot use it in this module (per the other comment from Copilot). So I think the change it is suggesting above makes the most sense.

[bdeshi]

sure i'll push an update soon.

[bdeshi]

@baolsen fixed with 563d0ef

[Copilot]

The source_organization variable should include validation to ensure it is not null when source_location is set to CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION. Currently, if a user sets source_location to the special value but forgets to provide source_organization, the scope_configuration block in main.tf will be created with a null name value, which will cause a runtime error.

Consider adding a validation block like:

validation {
  condition     = var.source_location != "CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION" || var.source_organization != null
  error_message = "source_organization must be provided when source_location is set to CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION."
}

Suggested change

	description = "Your Github organization name for organization-level webhook creation."
	description = "Your Github organization name for organization-level webhook creation."
	validation {
	condition = var.source_location != "CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION" || var.source_organization != null
	error_message = "source_organization must be provided when source_location is set to CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION."
	}

[baolsen]

Cross-parameter validation is only available from Terraform 1.9 so we cannot use it in this module.

[baolsen]

@bdeshi looks good to me, thanks for the contribution!