Skip to content

Module - GitHub App web hook

This module is treated as internal module, breaking changes will not trigger a major release bump.

The module can be deployed in two modes. 'Direct' messages, are delivered directly to the runner queues. 'EventBridge' messages are delivered to an EventBridge bus and then dispatched to the runner queues.

Lambda Function

The Lambda function is written in TypeScript and requires Node and yarn. Sources are located in [./lambdas/webhook]. Check see lambda.ts for the different handler functions available.

Install

cd lambdas/webhook
yarn install

Test

Test are implemented with Jest, calls to AWS and GitHub are mocked.

yarn run test

Package

To compile all TypeScript/JavaScript sources in a single file ncc is used.

yarn run dist

Requirements

Name Version
terraform >= 1.3.0
aws ~> 5.27
null ~> 3

Providers

Name Version
aws ~> 5.27

Modules

Name Source Version
direct ./direct n/a
eventbridge ./eventbridge n/a

Resources

Name Type
aws_apigatewayv2_api.webhook resource
aws_apigatewayv2_integration.webhook resource
aws_apigatewayv2_route.webhook resource
aws_apigatewayv2_stage.webhook resource
aws_ssm_parameter.runner_matcher_config resource

Inputs

Name Description Type Default Required
aws_partition (optional) partition for the base arn if not 'aws' string "aws" no
eventbridge Enable the use of EventBridge by the module. By enabling this feature events will be put on the EventBridge by the webhook instead of directly dispatching to queues for scaling.

enable: Enable the EventBridge feature.
accept_events: List can be used to only allow specific events to be putted on the EventBridge. By default all events, empty list will be be interpreted as all events.
object({
enable = optional(bool, false)
accept_events = optional(list(string), null)
})
n/a yes
github_app_parameters Parameter Store for GitHub App Parameters.
object({
webhook_secret = map(string)
})
n/a yes
kms_key_arn Optional CMK Key ARN to be used for Parameter Store. string null no
lambda_architecture AWS Lambda architecture. Lambda functions using Graviton processors ('arm64') tend to have better price/performance than 'x86_64' functions. string "arm64" no
lambda_memory_size Memory size limit in MB for lambda. number 256 no
lambda_runtime AWS Lambda runtime. string "nodejs20.x" no
lambda_s3_bucket S3 bucket from which to specify lambda functions. This is an alternative to providing local files directly. string null no
lambda_security_group_ids List of security group IDs associated with the Lambda function. list(string) [] no
lambda_subnet_ids List of subnets in which the action runners will be launched, the subnets needs to be subnets in the vpc_id. list(string) [] no
lambda_tags Map of tags that will be added to all the lambda function resources. Note these are additional tags to the default tags. map(string) {} no
lambda_timeout Time out of the lambda in seconds. number 10 no
lambda_zip File location of the lambda zip file. string null no
log_level Logging level for lambda logging. Valid values are 'silly', 'trace', 'debug', 'info', 'warn', 'error', 'fatal'. string "info" no
logging_kms_key_id Specifies the kms key id to encrypt the logs with string null no
logging_retention_in_days Specifies the number of days you want to retain log events for the lambda log group. Possible values are: 0, 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, and 3653. number 180 no
matcher_config_parameter_store_tier The tier of the parameter store for the matcher configuration. Valid values are Standard, and Advanced. string "Standard" no
prefix The prefix used for naming resources string "github-actions" no
repository_white_list List of github repository full names (owner/repo_name) that will be allowed to use the github app. Leave empty for no filtering. list(string) [] no
role_path The path that will be added to the role; if not set, the environment name will be used. string null no
role_permissions_boundary Permissions boundary that will be added to the created role for the lambda. string null no
runner_matcher_config SQS queue to publish accepted build events based on the runner type. When exact match is disabled the webhook accepts the event if one of the workflow job labels is part of the matcher. The priority defines the order the matchers are applied.
map(object({
arn = string
id = string
fifo = bool
matcherConfig = object({
labelMatchers = list(list(string))
exactMatch = bool
priority = optional(number, 999)
})
}))
n/a yes
ssm_paths The root path used in SSM to store configuration and secrets.
object({
root = string
webhook = string
})
n/a yes
tags Map of tags that will be added to created resources. By default resources will be tagged with name and environment. map(string) {} no
tracing_config Configuration for lambda tracing.
object({
mode = optional(string, null)
capture_http_requests = optional(bool, false)
capture_error = optional(bool, false)
})
{} no
webhook_lambda_apigateway_access_log_settings Access log settings for webhook API gateway.
object({
destination_arn = string
format = string
})
null no
webhook_lambda_s3_key S3 key for webhook lambda function. Required if using S3 bucket to specify lambdas. string null no
webhook_lambda_s3_object_version S3 object version for webhook lambda function. Useful if S3 versioning is enabled on source bucket. string null no

Outputs

Name Description
dispatcher n/a
endpoint_relative_path n/a
eventbridge n/a
gateway n/a
lambda n/a
lambda_log_group n/a
role n/a
webhook n/a