Other organizations

Implementers can call these workflows from their own GitHub organizations to build, test and publish OpenMRS frontend and backend modules under their own npm scopes and Maven repositories. Forks work too, including forks of OpenMRS repositories.

This page covers the minimum setup. For complete caller workflows, including tagged releases, see Full examples.

What changes outside OpenMRS

Behaviour	Inside `openmrs`	Elsewhere
Publishing npm packages, deploying SNAPSHOTs and releasing Maven modules	On by default	Off unless the caller turns it on
Publishing `@openmrs/*` or `openmrs` to the public npm registry	Allowed	Fails
Deploying to OpenMRS Maven repositories, or `org.openmrs*` groupIds to Maven Central	Allowed	Fails
Reference Application build after a frontend pre-release	On by default	Only if you set `downstream_repository`

Turning publishing on

Outside the openmrs organization, the workflows build but do not publish until the caller says so: publish on the release workflows and deploy_snapshots on the Maven build workflows. Set them from the repository owner rather than to true:


    with:
      publish: ${{ github.repository_owner == 'my-org' }}

A fork of your repository, or of an OpenMRS one, runs the same caller workflow but under a different owner, so its pushes build without running the release. Without this, a release run by hand fails and says how to turn it on.

Names OpenMRS owns

The remaining restrictions only cover names and repositories OpenMRS owns publicly. Publishing @openmrs/my-package to a private registry, or deploying to your own Maven repository, works as usual. See Publishing.

Setting up a frontend module

Check the repository fits

The workflows support Yarn Berry projects at the repository root. Repositories created from the O3 template already fit.

Choose how to authenticate to npm

Either configure npm trusted publishing for each package (recommended), or store an npm token as a secret.

Add the caller workflow

.github/workflows/ci.yml


on:
  push:
    branches: [main]
  pull_request:
 
jobs:
  build:
    uses: openmrs/openmrs-contrib-gha-workflows/.github/workflows/build-frontend-module.yml@main
 
  release:
    needs: build
    permissions:
      contents: write
      id-token: write
    uses: openmrs/openmrs-contrib-gha-workflows/.github/workflows/release-frontend-module.yml@main
    with:
      publish: ${{ github.repository_owner == 'my-org' }}

Pushes to the default branch publish a pre-release to the next dist-tag, using npm trusted publishing. Only if you cannot use it, pass a token as the NPM_AUTH_TOKEN secret. See Release frontend module for tagged releases.

Setting up a backend module

.github/workflows/build.yml


on:
  push:
    branches: [main, master]
  pull_request:
 
jobs:
  build:
    uses: openmrs/openmrs-contrib-gha-workflows/.github/workflows/build-backend-module.yml@main
    with:
      deploy_snapshots: ${{ github.repository_owner == 'my-org' }}
      # Optional: deploy SNAPSHOTs somewhere other than <distributionManagement>.
      maven_snapshot_repository_url: https://maven.example.org/snapshots
    secrets:
      MAVEN_REPO_USERNAME: ${{ secrets.MY_MAVEN_USER }}
      MAVEN_REPO_API_KEY: ${{ secrets.MY_MAVEN_PASSWORD }}

Without a Maven repository to deploy to, leave deploy_snapshots out and drop the secrets. Releases use Release backend module, which also needs publish set.

Things to know

Secret names. The workflows declare fixed secret names. secrets: inherit passes your secrets under their own names and does not rename them, so map differently named secrets explicitly, as above.

Caller permissions. A called workflow cannot be granted more than its caller. Give the calling job every permission the workflow’s jobs request (listed on each workflow page), or the run fails at startup.
Versions. Call the workflows at @main until versioned tags are published.
Branch protection. Release workflows push a commit and tag to your default branch. If it is protected, put the GitHub App, or the owner of the token you pass, on the ruleset bypass list; see Bot authentication.
Conventions are opt-in. The PR title and description checks encode OpenMRS conventions; use them only if you follow those conventions. The Transifex and OWASP Dependency-Check workflows are for OpenMRS repositories only.