OpenMRS repositories

Repositories in the OpenMRS organization get the full behaviour of every workflow: SNAPSHOT deploys to the OpenMRS Maven repository, npm publishing under @openmrs, the Reference Application build trigger and the security dashboard sync. The credentials they need live in organization secrets.

Frontend (O3) modules

One workflow file builds every pull request and push, publishes a pre-release from main, and cuts tagged releases on demand:

.github/workflows/ci.yml


name: OpenMRS CI
 
on:
  workflow_dispatch:
    inputs:
      release_type:
        description: 'Release version bump'
        type: choice
        options: [patch, minor, major]
        default: patch
      custom_version:
        description: 'Custom version (e.g. 12.5.0). Overrides the version bump.'
        required: false
      publish_only:
        description: 'Re-publish an existing tag after a failed npm publish. Set "Custom version" to it.'
        type: boolean
        default: false
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
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:
      release_type: ${{ inputs.release_type }}
      release_version: ${{ inputs.custom_version }}
      publish_only: ${{ inputs.publish_only || false }}
      publish_environment: npm-publish
    secrets:
      APP_ID: ${{ secrets.OMRS_ESM_RELEASE_APP_ID }}
      APP_PRIVATE_KEY: ${{ secrets.OMRS_ESM_RELEASE_APP_PRIVATE_KEY }}

O3 packages publish with npm trusted publishing, so no npm token is passed. The package’s trusted publisher on npmjs must name this caller file (ci.yml) and the npm-publish environment.
The release job’s permissions must include everything the release workflow’s jobs request: a called workflow cannot be granted more than its caller.
Add PR title and PR description checks and translation sync as separate jobs or workflows.

Backend (Maven) modules

.github/workflows/build.yml


name: Build with Maven
 
on:
  push:
    branches: [master, main]
  pull_request:
 
jobs:
  build:
    uses: openmrs/openmrs-contrib-gha-workflows/.github/workflows/build-backend-module.yml@main
    secrets:
      MAVEN_REPO_USERNAME: ${{ secrets.MAVEN_REPO_USERNAME }}
      MAVEN_REPO_API_KEY: ${{ secrets.MAVEN_REPO_API_KEY }}

.github/workflows/release.yml


name: Release
 
on:
  workflow_dispatch:
    inputs:
      release_version:
        description: 'Release version (e.g. 1.3.3). Defaults to the POM version without -SNAPSHOT.'
        required: false
      development_version:
        description: 'Next development version (e.g. 1.4.0-SNAPSHOT)'
        required: false
 
jobs:
  release:
    uses: openmrs/openmrs-contrib-gha-workflows/.github/workflows/release-backend-module.yml@main
    permissions:
      contents: write
    with:
      release_version: ${{ inputs.release_version }}
      development_version: ${{ inputs.development_version }}
    secrets:
      MAVEN_REPO_USERNAME: ${{ secrets.MAVEN_REPO_USERNAME }}
      MAVEN_REPO_API_KEY: ${{ secrets.MAVEN_REPO_API_KEY }}
      GPG_PRIVATE_KEY: ${{ secrets.GPG_PRIVATE_KEY }}
      GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
      APP_ID: ${{ secrets.OMRS_MODULE_RELEASE_APP_ID }}
      APP_PRIVATE_KEY: ${{ secrets.OMRS_MODULE_RELEASE_APP_PRIVATE_KEY }}

Use Build Maven project instead of the backend module build for Maven projects that are not OpenMRS modules (no .omod). Coverage needs a small stub workflow in the module repository.

Conventions

Area	Convention
Branches	Pre-releases and SNAPSHOTs come from the default branch; maintenance lines use `N.x` / `N.N.x` (backend) or `patch/*` (frontend)
Tags	Frontend releases tag `v<version>`; backend tags follow the POM’s `tagNameFormat`
Pull request titles	`(type) TICKET-123: Description`; see Frontend PR title check
Credentials	GitHub Apps rather than personal access tokens; see Bot authentication

These workflows run with OpenMRS defaults inside the openmrs organization. Outside it, publishing names OpenMRS owns is skipped; see Other organizations.