Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

The GitHub Action

This repository is a GitHub Action, versioned by the same vX.Y.Z tags as the binary and image. It needs Docker on the runner (every GitHub-hosted Linux runner has it).

A complete workflow

Pin every uses: to a full commit SHA with the tag in a trailing comment.

name: openEHR conformance
on: [pull_request]

permissions: {}

jobs:
  conformance:
    runs-on: ubuntu-latest
    permissions:
      contents: read # the checkout below, and nothing else
    services:
      cdr:
        image: registry.example/our-cdr:1.4.2
        ports: ["8080:8080"]
        options: >-
          --health-cmd "curl -fsS http://127.0.0.1:8080/health"
          --health-interval 5s --health-retries 30
    steps:
      - uses: actions/checkout@<commit-sha> # vN
        with:
          persist-credentials: false

      - id: veredictum
        uses: Vernum-Projecten/Veredictum@<commit-sha> # vX.Y.Z
        # Only for a CDR that wants bearer tokens; see "Credentials" below for
        # a CDR that wants a username and password, or no login.
        env:
          VEREDICTUM_CDR_TOKEN: ${{ secrets.CDR_TOKEN }}
          VEREDICTUM_CDR_ADMIN_TOKEN: ${{ secrets.CDR_ADMIN_TOKEN }}
        with:
          base-url: http://127.0.0.1:8080/openehr/v1
          statement: conformance/statement.json
          ixit: conformance/ixit.json
          auth: bearer
          admin-auth: bearer
          out-dir: conformance-results

      - uses: actions/upload-artifact@<commit-sha> # vN
        if: ${{ !cancelled() }}
        with:
          name: conformance-views
          path: |
            conformance-results/results.json
            conformance-results/junit.xml
            conformance-results/ctrf.json
            conformance-results/summary.md
            conformance-results/badges/

Leave recording.har out of uploads: it holds response bodies verbatim, which can include patient data. The CTRF view feeds reporters such as ctrf-io/github-test-reporter (a pull request comment needs pull-requests: write).

What the step does

  1. Pulls the image and records its ID.
  2. Runs test, writing results.json and recording.har into out-dir.
  3. Runs export (junit.xml, ctrf.json, summary.md), appends the summary and image to the job summary, and writes annotations.
  4. Runs badge into out-dir/badges/ and pushes to badge-branch if set (badges).
  5. Exits with the run’s status.
Exit statusMeaningThe step
0no row counts against the server and none is inconclusive: every row passed or was skipped, or failed only as a warningpasses
1a row counts against the server: it failed (a warning row excepted), or errored with the server named, whatever else the run holdsfails
2the run could not start or finish: a usage error, a catalogue gate finding, an unreadable file, a missing credentialfails
3no row counts against the server, and at least one is inconclusive: the instrument could not judge it, so it does not count against the vendorfails, or passes with fail-on-inconclusive: false

With exit 3 and fail-on-inconclusive: false, exit-code still reads 3 and the job summary lists each inconclusive row. The action clears its own files from out-dir first, so stale results are never exported.

Inputs

InputDefaultMeaning
base-urlrequiredthe server’s base URL, up to and including the openEHR REST base
statementnonepath to the party’s statement, which decides what runs (test)
ixitnonepath to the party’s IXIT, which answers the declared inputs
authnonenone, basic or bearer
admin-authnonethe same, for the administrative principal; with none the administrative workflows are skipped
documentsnonedocument ids separated by white space; a narrowed run is a working tool, never the record you submit
profiledevelopmentthe specification text the citations are read against: development (the pinned master of each openEHR repository) or released (the frozen release); only a released run backs a released claim or a certificate
platform-urlnonethe SMART Platform base URL (below); without it every workflow sent to the Platform is skipped as not-declared
out-dirveredictum-resultswhere the five files and the badges/ directory are written
imagethe release imagethe image to run (below)
pulltruefalse runs an image already on the runner, such as one built earlier in the job
networkhostthe container network the run joins
badge-branchnonea branch of your repository to push the badges to (below); with none, nothing is pushed
fail-on-inconclusivetruefalse lets exit status 3, a run whose only red rows are inconclusive, pass the step (above)
annotationstruefalse writes no annotations

With network: host, a service container is at 127.0.0.1 on its published port.

Outputs: exit-code, results, junit, ctrf, summary, badges, image-id and image-digests.

Credentials

Never an input; set them as env: on the step.

Your CDR wantsInputenv: on the step
no loginauth: none (the default)nothing
a username and passwordauth: basicVEREDICTUM_CDR_USER, VEREDICTUM_CDR_PASSWORD
a bearer tokenauth: bearerVEREDICTUM_CDR_TOKEN

admin-auth uses VEREDICTUM_CDR_ADMIN_USER and VEREDICTUM_CDR_ADMIN_PASSWORD, or VEREDICTUM_CDR_ADMIN_TOKEN. A _FILE variable is mounted read-only into the container; an empty variable counts as unset and stops the run with exit 2 (Logging in to the CDR).

      - uses: Vernum-Projecten/Veredictum@<commit-sha> # vX.Y.Z
        env:
          VEREDICTUM_CDR_USER: ${{ secrets.CDR_USER }}
          VEREDICTUM_CDR_PASSWORD: ${{ secrets.CDR_PASSWORD }}
        with:
          base-url: http://127.0.0.1:8080/openehr/v1
          statement: conformance/statement.json
          auth: basic

With no login, omit env: and auth:

      - uses: Vernum-Projecten/Veredictum@<commit-sha> # vX.Y.Z
        with:
          base-url: http://127.0.0.1:8080/openehr/v1
          statement: conformance/statement.json

SMART on openEHR

A server claiming smart adds platform-url (the SMART Platform base URL, which can differ from base-url) and the IXIT’s scoped_tokens (test):

The IXIT declaresenv: on the step
a test issuer under mintVEREDICTUM_SCOPED_TOKEN_KEY, the RSA private key in PEM
a token under issuedthe VEREDICTUM_SCOPED_TOKEN_<NAME> variable it names
      - uses: Vernum-Projecten/Veredictum@<commit-sha> # vX.Y.Z
        env:
          VEREDICTUM_CDR_TOKEN: ${{ secrets.CDR_TOKEN }}
          VEREDICTUM_SCOPED_TOKEN_KEY: ${{ secrets.SMART_TEST_ISSUER_KEY }}
        with:
          base-url: http://127.0.0.1:8080/openehr/v1
          platform-url: http://127.0.0.1:8080
          statement: conformance/statement.json
          ixit: conformance/ixit.json
          auth: bearer

A mint issuer signs a token per scope set; use only a key a test deployment trusts. Only VEREDICTUM_SCOPED_TOKEN_<NAME> variables reach the container. Working example: deploy/docker/e2e-ferroehr-smart.yml and deploy/docker/smart/.

Which image runs

By default ghcr.io/vernum-projecten/veredictum:X.Y.Z, the action’s own version; an image reporting another version is refused. To pin bytes, pass a digest:

        with:
          image: ghcr.io/vernum-projecten/veredictum@sha256:<digest>
docker buildx imagetools inspect ghcr.io/vernum-projecten/veredictum:X.Y.Z

The step runs by resolved image ID and reports it as image-id.

Annotations

An error per failed or errored row, a warning per warning row:

Error: ehr/create_ehr-same_ehr_twice-with_id row 1
Failed: counts against the server.
Checked: Create an EHR with the same ehr_id again.
Cited: "Can happen when the supplied `ehr_id` is already used by an existing EHR." (specs/openehr/ITS-REST/specifications/responses/409_EHR_with_id.yaml, description)
Expected: status 409
Received: status 201

GitHub shows at most 10 of each kind per step (limits); the step writes the first 10 in row order, then one notice counting the rest.

Badges

Four badges per run go to out-dir/badges/. With badge-branch: <branch> they are pushed there, only from a non-pull-request run on the default branch. See Badges.

Permissions

Without badge-branch: no GitHub API and no token; the job needs only contents: read. With it: set GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} in the step’s env: and grant contents: write.