Eureka CI GitHub Application

This page describes the Eureka CI GitHub Application — the serverless event router that bridges GitHub webhook events to GitHub Actions workflows across all FOLIO Eureka application repositories.

Overview

The Eureka CI GitHub Application is a serverless AWS application that serves as the central event router for the CI/CD system. It receives webhook events from GitHub (such as pull request creation, check suite completion, and merge queue requests), matches them against a configuration mapping, and triggers the appropriate GitHub Actions workflows in the target repositories.

The application enables automated CI/CD responses without requiring individual repositories to define complex workflow trigger logic. All event-to-workflow routing is managed centrally through an externalized configuration file.

Architecture

The application consists of eight components working together to route events from GitHub to GitHub Actions workflows:

Open

1. GitHub Webhook Events — GitHub sends signed webhook POST requests for configured event types (check_suite, pull_request, merge_group, push, check_run) to the application's endpoint. Each event includes the repository, branch, and action context.

2. Amazon API Gateway — exposes the HTTPS webhook endpoint that receives GitHub's POST requests. The API Gateway forwards each request to the webhook handler Lambda function.

3. Webhook Handler (Lambda) — the first Lambda function (webhook_handler). It validates the HMAC-SHA256 signature of each incoming webhook to verify the request is genuinely from GitHub, then queues the validated event to SQS for asynchronous processing.

4. Amazon S3 Configuration File — an externalized JSON configuration file stored in S3. This file defines the mapping between GitHub events and target workflows — specifying which repositories, event types, actions, and branch patterns should trigger which workflows with which input parameters.

5. SQS Queues — a primary queue for event processing and a dead-letter queue (DLQ) for events that fail processing after the configured retry attempts. The queue decouples event reception from processing, ensuring no events are lost during high-volume periods.

6. Queue Handler — checkProcessor (Lambda) — the second Lambda function (checkProcessor). It reads events from the SQS queue, loads the configuration from S3, matches each event against the configured rules, and triggers the appropriate GitHub Actions workflow via the GitHub API (workflow_dispatch or repository_dispatch).

7. GitHub Workflows — the target workflows that are triggered in the appropriate repositories. These include CI validation workflows (pr-check.yml), post-merge flows (post-merge-flow.yml), and branch ruleset automation (branch-ruleset-automation.yml).

8. CloudWatch Monitoring — dashboards and alarms for monitoring Lambda execution errors, SQS queue depth, and processing latency. Alerts are configured for Lambda invocation failures and DLQ message accumulation.

Event-to-Workflow Mapping

The following table shows the primary event types and the workflows they trigger:

How Workflows Are Triggered

The GitHub Application uses a flexible matching and variable substitution system:

Repository matching — events are matched against repository patterns in the configuration (e.g., folio-org/app-*). This allows a single configuration entry to cover all application repositories.

Branch matching — events can be filtered by branch patterns. The configuration supports both base branch and head branch constraints, including wildcard matching. For example, push events can be restricted to the default branch only.

File pattern filtering — push events can be filtered by the files that were changed. For example, the branch ruleset automation is triggered only when .github/update-config.yml is modified on the default branch.

Variable substitution — when dispatching a workflow, the application substitutes event-specific variables into the workflow input parameters:

Which CI Processes Depend on the GitHub Application

The following CI/CD processes are triggered by the Eureka CI GitHub Application:

• PR validation (pr-check.yml) — triggered on check_suite, check_run, and pull_request events. Runs module interface integrity and dependencies integrity validation on version-update PRs. See Managing Release Branch Updates — CI Validation.

• Post-merge flow (post-merge-flow.yml) — triggered when a pull_request is closed with merged: true. Publishes the application descriptor to FAR, deletes the update branch, and sends Slack notifications. See Managing Release Branch Updates — Post-Merge Processing.

• Branch ruleset automation (branch-ruleset-automation.yml) — triggered on push events to the default branch when update-config.yml is modified. Creates or updates GitHub branch rulesets for release branches. See Branch Ruleset Automation.

• Merge queue checks (pr-check.yml in kitfox-github) — triggered on merge_group events when the merge queue validates queued PRs before merging.

Monitoring and Troubleshooting

CloudWatch dashboards provide visibility into:

• Lambda invocation counts and error rates

• SQS queue depth (messages waiting to be processed)

• Processing latency (time from event receipt to workflow dispatch)

Dead-letter queue (DLQ) — events that fail processing after retry attempts are moved to the DLQ. Common causes include:

• GitHub API rate limiting

• Target workflow not found in the repository

• Invalid configuration mapping

Troubleshooting steps:

Related Pages

• Managing Release Branch Updates — the end-to-end update cycle that depends on the GitHub Application for CI triggering and post-merge processing

• Branch Ruleset Automation — ruleset management triggered by the GitHub Application

• Understanding Application Repository Files — Workflow Files — the workflows that are triggered by the GitHub Application