Getting Started with Metanorma in CI/CD Environments

Introduction

Continuous Integration (CI) and Continuous Deployment (CD) are crucial for managing and authoring documents with Metanorma.

CI/CD automates the process of building, testing, and deploying documents, ensuring that they are always up-to-date and consistent. This automation reduces manual errors, speeds up the release cycle, and allows for continuous feedback and improvement. By integrating Metanorma into CI/CD pipelines, users can streamline their document workflows, maintain high-quality standards, and focus on content creation rather than manual processes.

This guide provides an overview of how to integrate Metanorma into CI/CD platforms and run Metanorma in a CI/CD environment.

Principles

Integration of Metanorma into CI/CD environments consists of two phases:

Installing the Metanorma toolchain
Running Metanorma (through shell commands)

Metanorma provides a wide set of Docker images on Docker Hub.

Supported platforms

Metanorma provides official support for the following CI/CD platforms:

The following platforms are supported using the Metanorma Docker containers:

Using Metanorma on a CI/CD platform

GitHub (through GitHub Actions)

To compile Metanorma documents on GitHub, you can use GitHub Actions. GitHub Actions is a CI/CD service that allows you to automate your workflow directly from your GitHub repository.

To use Metanorma in GitHub Actions, you need to create a workflow file in your repository. The workflow file defines the steps that GitHub Actions will run when a specific event occurs, such as a push to a branch or a pull request.

Metanorma provides a set of re-useable GitHub Actions at actions-mn that you can use in your workflow.

The following is an example of a GitHub Actions workflow file that generates a Metanorma site and deploys it to GitHub Pages.

Metanorma provides the following actions in the actions-mn repository.

actions-mn/setup: Installs Metanorma (and the metanorma CLI) for Ubuntu, MacOS, or Windows.

This action can be skipped if you run CI in a Docker environment and use the Metanorma Docker image as Metanorma is already installed.
actions-mn/cache: Caches files used by and generated by Metanorma during compilation (temporary fonts, Relaton data) to speed up subsequent runs.
actions-mn/build-and-publish: Generates a Metanorma site (using the default filename metanorma.yml) and uploads artifacts for deployment.

For complete workflow examples, please refer to the documentation of the actions-mn/build-and-publish action.

Example 1. .github/workflows/generate.yml file for generating a Metanorma site and deploying it to GitHub Pages

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

GitLab (using GitLab CI)

GitLab CI is a continuous integration service built into GitLab that allows you to automate your workflow directly from your GitLab repository.

To use Metanorma in GitLab CI, you need to create a .gitlab-ci.yml file in your repository. The .gitlab-ci.yml file defines the steps that GitLab CI will run when a specific event occurs, such as a push to a branch or a merge request.

Metanorma uses the metanorma/metanorma Docker image to run Metanorma in GitLab CI.

Metanorma provides a set of re-useable GitLab CI configurations at the metanorma/ci repository (on GitHub, not GitLab).

The workflows can be reused as follows.

Example 2. .gitlab-ci.yml file for generating a Metanorma site and deploying it to GitLab Pages through workflow inclusion

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

The following is an example of a full .gitlab-ci.yml file that generates a Metanorma site and deploys it to GitLab Pages, allowing for customization.

Example 3. .gitlab-ci.yml file for generating a Metanorma site and deploying it to GitLab Pages

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

Other platforms (using Docker)

Metanorma can be used on other CI/CD platforms by leveraging Docker. The following examples demonstrate how to set up Metanorma on Travis CI, CircleCI, Jenkins, and Bitrise using Docker.

Travis CI

To use Metanorma in Travis CI, you need to create a .travis.yml file in your repository. The .travis.yml file defines the steps that Travis CI will run when a specific event occurs, such as a push to a branch or a pull request.

Example 4. .travis.yml file for generating a Metanorma site

language: minimal

services:
  - docker

before_install:
  - docker pull metanorma/metanorma

script:
  - docker run --rm -v $(pwd):/metanorma metanorma/metanorma metanorma site generate --agree-to-terms

CircleCI

To use Metanorma in CircleCI, you need to create a .circleci/config.yml file in your repository. The .circleci/config.yml file defines the steps that CircleCI will run when a specific event occurs, such as a push to a branch or a pull request.

Example 5. .circleci/config.yml file for generating a Metanorma site

version: 2.1

jobs:
  build:
    docker:
      - image: metanorma/metanorma
    steps:
      - checkout
      - run:
          name: Generate Metanorma site
          command: metanorma site generate --agree-to-terms

workflows:
  version: 2
  build:
    jobs:
      - build

Jenkins

To use Metanorma in Jenkins, you need to create a Jenkinsfile in your repository. The Jenkinsfile defines the steps that Jenkins will run when a specific event occurs, such as a push to a branch or a pull request.

Example 6. Jenkinsfile for generating a Metanorma site

pipeline {
    agent {
        docker {
            image 'metanorma/metanorma'
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'metanorma site generate --agree-to-terms'
            }
        }
    }
}

Bitrise

To use Metanorma in Bitrise, you need to create a bitrise.yml file in your repository. The bitrise.yml file defines the steps that Bitrise will run when a specific event occurs, such as a push to a branch or a pull request.

Example 7. bitrise.yml file for generating a Metanorma site

format_version: '8'
default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git

workflows:
  primary:
    steps:
      - git-clone: {}
      - docker-compose:
          inputs:
            - content: |
                version: '3'
                services:
                  metanorma:
                    image: metanorma/metanorma
                    volumes:
                      - .:/metanorma
                    command: metanorma site generate --agree-to-terms