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 installingmetanorma
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:
-
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