Getting Started with Metanorma in CI/CD Environments

Metanorma is often run on continuous integration (CI) and continuous deployment (CD) environments.

Running on CI/CD platforms

Because metanorma provides a CLI toolchain it’s straightforward to integrate it with any CI/CD platform.

Because we use GitHub/GitLab for development integration with those CI platforms

GitHub Actions

An example of the workflow for GitHub Actions may look like this:

---
name: generate

on: push: branches: [ main ] pull_request: workflow_dispatch:

permissions: contents: read pages: write id-token: write

concurrency: group: "pages" cancel-in-progress: true

jobs: build: runs-on: ubuntu-latest container: image: metanorma/metanorma:latest steps: - name: Checkout uses: actions/checkout@v3

name: Cache Metanorma assets uses: actions-mn/cache@v1

name: Metanorma generate site uses: actions-mn/build-and-publish@main with: token: ${{ secrets.GITHUB_TOKEN }} agree-to-terms: true

  deploy:
    if: ${{ github.ref == 'refs/heads/main' }}
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1
---

In the workflow above doesn’t fit your needs you can create your own workflow based on a list of actions that metanorma provides:

actions-mn/setup - used for installing metanorma CLI for Ubuntu, MacOS, or Windows
actions-mn/cache - caches intermediate metanorma files (fonts, relaton data) to speedup compilation
actions-mn/build-and-publish - do site generation and upload artifact for deployment

The actions-mn/setup GitHub Action can be skipped if you run CI in a Docker environment and use the Metanorma Docker image.

For complete workflow examples just check README for actions-mn/build-and-publish action

GitLab CI

An example of the workflow for GitHub Actions may look like this:

---
image:
  name: metanorma/metanorma
  entrypoint: [ "" ]

cache: paths:

stages: - build - deploy

build: stage: build script: - curl -L --retry 3 https://raw.githubusercontent.com/metanorma/ci/main/gemfile-to-bundle-add.sh | bash - bundle install - metanorma site generate --output-dir public --agree-to-terms .

artifacts:
  paths:
    - public

pages: dependencies: - build stage: deploy script: - | curl --location --output artifacts.zip --header "JOB-TOKEN: $CI_JOB_TOKEN" \ "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/master/download?job=build" artifacts: paths: - public only: - master - main ---

If it is suitable for you you can reuse it with the following code (to minimize code duplication):

---
include:
- remote: 'https://raw.githubusercontent.com/metanorma/ci/main/cimas-config/gitlab-ci/samples/docker.shared.yml'
---

Other CI providers

Generally, the integration consists of 2 phases:

installing metanorma toolchain
calling metanorma-cli by shell commands

Most CI providers nowadays allow to run CI from a Docker execution environment:

Metanorma provides a wide set of docker images https://hub.docker.com/r/metanorma you can select what is suitable for you