# govuk-pay/pay-ci architecture

> Architecture diagram of the GitHub repository govuk-pay/pay-ci, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/govuk-pay/pay-ci
- Repository: https://github.com/govuk-pay/pay-ci

## Overview

pay-ci is a Concourse-based CI and operational-automation repository. Its broad workflow is pipeline orchestration over reusable tasks that build, test, deploy, and maintain GOV.UK Pay services. Sampled code also shows a CodeBuild runner that starts builds and streams logs, a support-rota tool that resolves on-call contacts and updates Slack, and a semantic-version action. Most pipeline/task internals are unsampled, so those subsystem links are shown as unverified rather than asserted as source-proven calls.

Main entry points: [`ci/scripts/support-rota-notification/index.js`](https://github.com/govuk-pay/pay-ci/blob/master/ci/scripts/support-rota-notification/index.js) (Support rota command), [`ci/scripts/run-codebuild/libs/codebuild-runner.js`](https://github.com/govuk-pay/pay-ci/blob/master/ci/scripts/run-codebuild/libs/codebuild-runner.js) (Build and log runner), [`ci/pipelines`](https://github.com/govuk-pay/pay-ci/tree/master/ci/pipelines) (Pipelines), [`ci/scripts/run-codebuild/libs/executor.js`](https://github.com/govuk-pay/pay-ci/blob/master/ci/scripts/run-codebuild/libs/executor.js) (Build executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["CI orchestration"]
  node_pipelines["Pipelines"]
  node_pkl["Pkl pipelines"]
  node_tasks["Reusable tasks"]
end

subgraph group_delivery["Delivery and testing"]
  node_codebuild_entry["CodeBuild command<br/>[run-codebuild.js]"]
  node_executor["Build executor<br/>[executor.js]"]
  node_codebuild_runner["Build and log runner"]
end

subgraph group_operations["Operations automation"]
  node_rota_entry["Support rota command<br/>[index.js]"]
  node_user_mapping["User mapping"]
  node_slack_client["Slack updates<br/>[slack-client.js]"]
  node_secrets[("Pass secrets")]
end

subgraph group_utilities["Reusable tools"]
  node_semver_entry["Semver action entry<br/>[index.ts]"]
  node_semver_logic["Version calculation<br/>[nextSemver.ts]"]
end

node_concourse(("Concourse"))
node_github(("GitHub Actions"))
node_codebuild_service["AWS CodeBuild"]
node_cloudwatch["CloudWatch Logs"]
node_pagerduty["PagerDuty schedules"]
node_slack["Slack"]

node_concourse -.->|"runs"| node_pipelines
node_pipelines -.->|"dispatches"| node_tasks
node_pkl -.->|"defines"| node_pipelines
node_github -.->|"invokes"| node_semver_entry
node_semver_entry -->|"calls"| node_semver_logic
node_codebuild_entry -->|"calls"| node_executor
node_executor -->|"creates and runs"| node_codebuild_runner
node_codebuild_runner -->|"starts and polls"| node_codebuild_service
node_codebuild_runner -->|"reads logs"| node_cloudwatch
node_rota_entry -->|"queries schedules"| node_pagerduty
node_rota_entry -->|"resolves handles"| node_user_mapping
node_rota_entry -->|"updates and notifies"| node_slack_client
node_slack_client -->|"posts updates"| node_slack
node_secrets -.->|"provides credentials"| node_rota_entry

click node_pipelines "https://github.com/govuk-pay/pay-ci/tree/master/ci/pipelines"
click node_pkl "https://github.com/govuk-pay/pay-ci/tree/master/ci/pkl-pipelines"
click node_tasks "https://github.com/govuk-pay/pay-ci/tree/master/ci/tasks"
click node_semver_entry "https://github.com/govuk-pay/pay-ci/blob/master/actions/next-semver/src/index.ts"
click node_semver_logic "https://github.com/govuk-pay/pay-ci/blob/master/actions/next-semver/src/nextSemver.ts"
click node_codebuild_entry "https://github.com/govuk-pay/pay-ci/blob/master/ci/scripts/run-codebuild/run-codebuild.js"
click node_executor "https://github.com/govuk-pay/pay-ci/blob/master/ci/scripts/run-codebuild/libs/executor.js"
click node_codebuild_runner "https://github.com/govuk-pay/pay-ci/blob/master/ci/scripts/run-codebuild/libs/codebuild-runner.js"
click node_rota_entry "https://github.com/govuk-pay/pay-ci/blob/master/ci/scripts/support-rota-notification/index.js"
click node_user_mapping "https://github.com/govuk-pay/pay-ci/blob/master/ci/scripts/support-rota-notification/access-control-util.js"
click node_slack_client "https://github.com/govuk-pay/pay-ci/blob/master/ci/scripts/support-rota-notification/slack-client.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pipelines,node_pkl,node_tasks toneBlue
class node_codebuild_entry,node_executor,node_codebuild_runner toneAmber
class node_rota_entry,node_user_mapping,node_slack_client,node_secrets toneMint
class node_semver_entry,node_semver_logic toneRose
class node_concourse,node_github,node_codebuild_service,node_cloudwatch,node_pagerduty,node_slack toneIndigo
```

## Components

### CI orchestration

- [Pipelines](https://github.com/govuk-pay/pay-ci/tree/master/ci/pipelines): `ci/pipelines`
- [Pkl pipelines](https://github.com/govuk-pay/pay-ci/tree/master/ci/pkl-pipelines): `ci/pkl-pipelines`
- [Reusable tasks](https://github.com/govuk-pay/pay-ci/tree/master/ci/tasks): `ci/tasks`

### Delivery and testing

- [CodeBuild command](https://github.com/govuk-pay/pay-ci/blob/master/ci/scripts/run-codebuild/run-codebuild.js): `ci/scripts/run-codebuild/run-codebuild.js`
- [Build executor](https://github.com/govuk-pay/pay-ci/blob/master/ci/scripts/run-codebuild/libs/executor.js): `ci/scripts/run-codebuild/libs/executor.js`
- [Build and log runner](https://github.com/govuk-pay/pay-ci/blob/master/ci/scripts/run-codebuild/libs/codebuild-runner.js): `ci/scripts/run-codebuild/libs/codebuild-runner.js`

### Operations automation

- [Support rota command](https://github.com/govuk-pay/pay-ci/blob/master/ci/scripts/support-rota-notification/index.js): `ci/scripts/support-rota-notification/index.js`
- [User mapping](https://github.com/govuk-pay/pay-ci/blob/master/ci/scripts/support-rota-notification/access-control-util.js): `ci/scripts/support-rota-notification/access-control-util.js`
- [Slack updates](https://github.com/govuk-pay/pay-ci/blob/master/ci/scripts/support-rota-notification/slack-client.js): `ci/scripts/support-rota-notification/slack-client.js`
- **Pass secrets**

### Reusable tools

- [Semver action entry](https://github.com/govuk-pay/pay-ci/blob/master/actions/next-semver/src/index.ts): `actions/next-semver/src/index.ts`
- [Version calculation](https://github.com/govuk-pay/pay-ci/blob/master/actions/next-semver/src/nextSemver.ts): `actions/next-semver/src/nextSemver.ts`

### Other components

- **Concourse**
- **GitHub Actions**
- **AWS CodeBuild**
- **CloudWatch Logs**
- **PagerDuty schedules**
- **Slack**

## Connections

- Concourse → Pipelines: runs
- Pipelines → Reusable tasks: dispatches
- Pkl pipelines → Pipelines: defines
- GitHub Actions → Semver action entry: invokes
- Semver action entry → Version calculation: calls (evidence: `actions/next-semver/src/index.ts`)
- CodeBuild command → Build executor: calls (evidence: `ci/scripts/run-codebuild/run-codebuild.js`)
- Build executor → Build and log runner: creates and runs (evidence: `ci/scripts/run-codebuild/libs/executor.js`)
- Build and log runner → AWS CodeBuild: starts and polls (evidence: `ci/scripts/run-codebuild/libs/codebuild-runner.js`)
- Build and log runner → CloudWatch Logs: reads logs (evidence: `ci/scripts/run-codebuild/libs/codebuild-runner.js`)
- Support rota command → PagerDuty schedules: queries schedules (evidence: `ci/scripts/support-rota-notification/index.js`)
- Support rota command → User mapping: resolves handles (evidence: `ci/scripts/support-rota-notification/index.js`)
- Support rota command → Slack updates: updates and notifies (evidence: `ci/scripts/support-rota-notification/index.js`)
- Slack updates → Slack: posts updates (evidence: `ci/scripts/support-rota-notification/slack-client.js`)
- Pass secrets → Support rota command: provides credentials
