GitHub Actions CI/CD Architecture

Use paths-ignore at the workflow trigger level to prevent unnecessary builds when only documentation or configuration files change:

The two push workflows must not ignore src/main/helm/** — they own the ArgoCD bump for their environment and would otherwise leave the manifest stale. See Helm changes (no separate pipeline).

Use the dorny/paths-filter action to conditionally run frontend or backend tests based on what files changed:

Conditional job execution creates a problem for branch protection: required status checks are matched by name, and Back-end / ✅ Test is legitimately skipped on a front-end-only PR. Requiring it directly would block those PRs.

The fix is one job that always runs, inspects its dependencies itself, and reports a single verdict. Require only that job.

In the Angular repositories needs also lists check-format, which has no if: and so always reports. See Formatting gate.

Behaviour:

The Angular repositories' pre-commit hook formats staged files but deliberately skips wherever it cannot run — see Formatting and the Pre-commit Hook. check-format.yml is what enforces formatting:

It checks out the pull request’s merge commit, soft-resets it to the merge base so every change is staged as one commit, and runs npx lint-staged --no-stash. The job fails if that changes the index or working tree, or if lint-staged itself fails.

Running lint-staged, rather than Prettier directly, is the point: the check applies the repository’s own glob, .prettierignore and commands, whatever lint-staged and Prettier versions the repository pins. Only changed files are checked, so a repository with existing drift adopts it without a mass reformat — at the cost that touching a drifted file requires formatting all of it.

pull_request events only. event-admin-ui references it at @main while its other jobs are pinned to a tag that predates it.

Workflow names use emoji prefixes for quick visual identification:

argocd-update.yml takes an optional spa-url. When set, the deploy is followed by a verify-spa-cache job that waits for the new build.version to appear at that URL, then asserts index.html does not revalidate to a stale copy:

The check is one conditional request:

That timestamp is Jib’s fixed reproducible-build time, so it is exactly the validator a browser cached from a broken build holds. A 304 means returning users keep running the previous release until they hard-reload.

Why this is a deployment check and not a unit test. Bugs #975 and #976 were omissions, not regressions — two services never received the index.html validator fix that a third had, and one carried the defect for about five months. A repo-local test can only protect code that already exists in that repo, so no test anywhere would have flagged either. This tests the deployed artefact, so it also covers chart edits, ingress rewrites and a CDN appearing in front of a host.

Requires the service to expose build.version, i.e. the build-info goal on spring-boot-maven-plugin. The job says so when the wait times out.

copilot-review.yml requests a Copilot code review on every new pull request. Each repository calls it from a thin wrapper at .github/workflows/copilot-review.yml:

When a PR is created or updated against non-main branches:

When code is pushed to the develop branch:

build-sha is passed only on develop. It writes podAnnotations."app.kubernetes.io/build-sha", forcing a pod rollover when the SNAPSHOT chart version has not changed but the image behind it has.

When code is pushed to the main branch (typically after a release merge):

When code is pushed to a release/** branch (created by manual-release-start.yml):

This is intentionally minimal — packaging, image build and chart push are deferred until the release branch is merged into main. The release branch is a candidate, not a deliverable.

Often nothing runs at all, and a release pull request reporting no checks is normal:

A workflow_dispatch trigger on manual-release-start.yml lets a human cut a release branch:

This is the only way new versions enter main. There is no direct push from develop to main.

Chart changes under src/main/helm/** travel with the branch’s normal pipeline: push-dev.yml on develop, push-main.yml on main. Both already call helm-build.yml and then argocd-update.yml, so the chart is packaged, pushed and deployed by the workflow that owns that environment.

pr-non-main.yml is the one place src/main/helm/* *should stay in paths-ignore — a chart edit needs no Java or Angular tests, and that workflow performs no deployment.

Project workflows reference reusable workflows using the uses keyword:

Recommended: Use @main to stay current with the latest reusable workflow improvements.

Alternative: Pin to a specific tag for stability when needed:

Use needs to define job dependencies:

The maven-package workflow caches the target/ directory, which is then reused by:

Use if: always() to run jobs even when dependencies were skipped:

Settings → Actions → General → Workflow permissions → "Read and write permissions".

The reusable workflows declare permissions: contents: write (e.g. dependencygraph.yml, gitflow-release-finish.yml). GitHub blocks reusable workflows from elevating beyond the calling workflow’s default GITHUB_TOKEN permissions. New repos default to read, which causes the calling workflow to fail with startup_failure and no jobs created — an opaque error with no log output.

This is the single most common bring-up mistake. Mirror what event-admin-service already has set.

CLI shortcut to flip it:

On the christhonie/event repo: Settings → Actions → General → Access → "Accessible from repositories owned by the user 'christhonie'".

Without this, calls to christhonie/event/.github/workflows/@main from a service repo fail with "workflow not found" or a permissions error. The default for new repos is "Not accessible". Once set to "user-owned", every existing and future repo under christhonie/ can consume the reusable workflows.

This setting is configured once on christhonie/event, not per service repo.

Settings → Branches → Add rule → develop → "Require status checks to pass before merging" → select PR checks.

Without this, the pipeline is advisory. admin-portal PR #85 merged with a red Back-end / ✅ Test, broke develop, and stayed broken through the next merge — the check was correct, nothing enforced it.

Require exactly one context: PR checks. Never require Back-end / ✅ Test or Front-end / ✅ Test directly; paths-filter skips them by design and a skipped required check is not a pass. See The pr-checks aggregator.

CLI equivalent:

strict: false is deliberate — strict: true forces every branch to be up to date with the base before merging, which serialises merges and adds little on a small team.

The service-name input passed to argocd-update.yml must match three things:

It does not need to match the GitHub repo name — for example, christhonie/ems-mcp-server ships chart name ems-mcp-server, image christhonie/ems-mcp-server, and manifest ems-mcp-server-prod.yml. The repo name happens to match in this case, but the convention links chart/image/manifest, not repo.

The EVENT_PACKAGE_REPO_TOKEN secret is internally mapped to workflow-specific variables:

The setup-java action creates a settings.xml file with credentials:

The generated settings.xml will contain:

Build artifacts (JAR files) are uploaded to GitHub Actions artifacts for investigation:

The dependencygraph workflow submits the Maven dependency graph to GitHub’s dependency graph feature, enabling: