diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 0000000000..ec43fff176 --- /dev/null +++ b/.github/workflows/README.md @@ -0,0 +1,81 @@ +# GitHub Actions workflows + +Workflows are split into **entry points** (triggered by GitHub events) and +**reusable building blocks** (file names starting with `_`, triggered only via +`workflow_call`). Entry points contain no build logic of their own; they just +compose the building blocks. + +## Entry points + +| Workflow | Trigger | Jobs | +|----------|---------|------| +| [`pr.yml`](pr.yml) (*PR*) | `pull_request`, manual `workflow_dispatch` | lint, build; then unit, UI and integration tests (after build succeeds) | +| [`branch.yml`](branch.yml) (*Branch*) | push to any branch except `master` | lint, build | +| [`merge.yml`](merge.yml) (*Merge to master*) | push to `master` | lint; build on Linux (x86_64 and aarch64), Windows and macOS (product archives uploaded as artifacts; a failing aarch64 build does not fail the workflow); unit, UI and integration tests; Docker images for the services | +| [`release.yml`](release.yml) (*Release*) | push of any tag | Docker images for the services | +| [`report.yml`](report.yml) (*Test report*) | `workflow_run` after *PR* or *Merge to master* completes | publishes JUnit results as check runs | + +`pr.yml` and `branch.yml` use a `concurrency` group, so a new push cancels the +still-running workflow for the same PR/branch. + +## Reusable workflows + +| Workflow | Purpose | Inputs | +|----------|---------|--------| +| [`_lint.yml`](_lint.yml) | Runs [pre-commit](../../.pre-commit-config.yaml) on the files changed between two refs | `from-ref`, `to-ref` | +| [`_build.yml`](_build.yml) | `mvn install -DskipTests` | `os` (default `ubuntu-latest`), `upload-artifacts` (upload `phoebus-product/target/*.{tar.gz,zip}`), `allow-failure` (set `continue-on-error` on the job) | +| [`_test.yml`](_test.yml) | Generic "run a test command, upload reports" job | `name`, `run`, `report-path` | +| [`_unit-test.yml`](_unit-test.yml) | `_test.yml` with `mvn verify` (surefire) | – | +| [`_ui-test.yml`](_ui-test.yml) | `_test.yml` with `xvfb-run -a mvn verify -P ui-tests` (TestFX, headless) | – | +| [`_integration-test.yml`](_integration-test.yml) | `-P it-tests,docker-tests` for `services/save-and-restore` against an Elasticsearch service container | – | +| [`_docker-image.yml`](_docker-image.yml) | Builds a service with Maven, then builds and pushes a multi-arch (amd64/arm64) image to `ghcr.io///` | `image-suffix`, `context`, `maven-args` | + +All jobs that need Java use the composite action +[`../actions/setup-java`](../actions/setup-java/action.yml) +(Temurin JDK with Maven dependency caching). + +### Lint ranges + +Only changed files are linted, because `master` is not yet clean for the +`end-of-file-fixer` / `trailing-whitespace` hooks: + +- PR: `pull_request.base.sha` … `pull_request.head.sha` +- Branch push: `origin/master` … pushed commit (`github.event.before` would be + the all-zero SHA on the first push of a new branch) +- Merge to master: `github.event.before` … pushed commit + +To reproduce locally: `pre-commit run --from-ref origin/master --to-ref HEAD`. + +### Docker images + +`merge.yml` and `release.yml` build images for these services (matrix): +`alarm-server`, `alarm-logger`, `save-and-restore`, `scan-server`. +Each is published as `service-`, built from `services/`. +`scan-server` additionally needs the `-Pexecutable-jar` Maven profile. +Image tags are derived by `docker/metadata-action` from the branch or tag name. + +### Test reports + +Test jobs upload their surefire/failsafe XML as artifacts named +`-reports` / `integration-test-reports`. Pull requests from forks only +get a read-only token, so they cannot publish check runs themselves. +`report.yml` therefore runs separately in the context of the base repository +(with `checks: write`), downloads all `*test-reports` artifacts of the +completed run and publishes them. It never checks out or runs PR code — keep +it that way (this is why the `dangerous-triggers` zizmor finding is +suppressed there). + +## Conventions + +- Default token permissions are `contents: read`; jobs that need more + (`packages: write` for Docker, `checks`/`pull-requests: write` for reports) + declare them explicitly. +- Third-party actions are pinned to a full commit SHA and + `persist-credentials: false` is set on checkout. The pre-commit hook + [zizmor](https://github.com/zizmorcore/zizmor) checks workflows for these + and other security issues. +- Untrusted or input-derived values are passed to `run:` steps through `env:` + variables rather than being interpolated with `${{ }}` directly. +- Action versions are bumped by Dependabot ([`../dependabot.yml`](../dependabot.yml)). + Manually pinned versions (JDK, Elasticsearch) are listed in + [`../CI_VERSIONS.md`](../CI_VERSIONS.md). diff --git a/.github/workflows/_build.yml b/.github/workflows/_build.yml index 1abd1fe4b8..c3cc8ecafd 100644 --- a/.github/workflows/_build.yml +++ b/.github/workflows/_build.yml @@ -11,6 +11,10 @@ on: description: Upload the product tarball/zip (used by the master build). type: boolean default: false + allow-failure: + description: Do not fail the calling workflow if this build fails. + type: boolean + default: false permissions: contents: read @@ -18,6 +22,7 @@ permissions: jobs: build: runs-on: ${{ inputs.os }} + continue-on-error: ${{ inputs.allow-failure }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: diff --git a/.github/workflows/merge.yml b/.github/workflows/merge.yml index e12506a221..0b927cfc47 100644 --- a/.github/workflows/merge.yml +++ b/.github/workflows/merge.yml @@ -18,11 +18,13 @@ jobs: strategy: fail-fast: false matrix: - os: [ubuntu-latest, windows-latest, macos-latest] + os: [ubuntu-latest, ubuntu-24.04-arm, windows-latest, macos-latest] uses: ./.github/workflows/_build.yml with: os: ${{ matrix.os }} upload-artifacts: true + # Linux aarch64 is not yet a supported platform; report but tolerate failures + allow-failure: ${{ startsWith(matrix.os, 'ubuntu-') && endsWith(matrix.os, '-arm') }} unit-test: uses: ./.github/workflows/_unit-test.yml ui-test: