Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: update cicd page #825

Merged
merged 1 commit into from
Oct 14, 2024
Merged

chore: update cicd page #825

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
236 changes: 207 additions & 29 deletions _pages/install/cicd.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,90 @@ title: Getting Started with Metanorma in CI/CD Environments
redirect_from:
- /setup/cicd
---
Metanorma is often run on continuous integration (CI) and continuous deployment
(CD) environments.

== Running on CI/CD platforms
== Introduction

Because metanorma provides a CLI toolchain it's straightforward to integrate it with any CI/CD platform.
Continuous Integration (CI) and Continuous Deployment (CD) are crucial for
managing and authoring documents with Metanorma.

Because we use GitHub/GitLab for development integration with those CI platforms
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.

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

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

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

* link:/install[Installing the Metanorma toolchain]
* Running Metanorma (through shell commands)

Metanorma provides a wide set of Docker images on
https://hub.docker.com/r/metanorma[Docker Hub].


== Supported platforms

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

* https://github.com/[GitHub Actions]
* https://gitlab.com/[GitLab CI]

The following platforms are supported using the Metanorma Docker containers:

* https://docs.travis-ci.com/user/docker/[Travis CI]
* https://circleci.com/docs/using-docker/[CircleCI]
* https://www.jenkins.io/doc/book/pipeline/docker/[Jenkins]
* https://devcenter.bitrise.io/en/infrastructure/using-your-own-docker-image.html[Bitrise]


== 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
https://github.com/actions-mn[`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
https://github.com/actions-mn[`actions-mn`] repository.

https://github.com/actions-mn/setup[`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.

https://github.com/actions-mn/cache[`actions-mn/cache`]::
Caches files used by and generated by Metanorma during compilation (temporary
fonts, Relaton data) to speed up subsequent runs.

https://github.com/actions-mn/build-and-publish[`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
https://github.com/actions-mn/build-and-publish[`actions-mn/build-and-publish` action].


.`.github/workflows/generate.yml` file for generating a Metanorma site and deploying it to GitHub Pages
[example]
====
[source,yml]
----
name: generate
Expand Down Expand Up @@ -67,21 +138,42 @@ jobs:
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:

* https://github.com/actions-mn/setup[`actions-mn/setup`] - used for installing `metanorma` CLI for Ubuntu, MacOS, or Windows
* https://github.com/actions-mn/cache[`actions-mn/cache`] - caches intermediate metanorma files (fonts, relaton data) to speedup compilation
* https://github.com/actions-mn/build-and-publish[`actions-mn/build-and-publish`] - do site generation and upload artifact for deployment
=== GitLab (using GitLab CI)

The https://github.com/actions-mn/setup[`actions-mn/setup` GitHub Action] can be skipped if you run CI in a Docker environment and use the Metanorma Docker image.
GitLab CI is a continuous integration service built into GitLab that allows you
to automate your workflow directly from your GitLab repository.

For complete workflow examples just check https://github.com/actions-mn/build-and-publish[README for `actions-mn/build-and-publish` action]
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.

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

An example of the workflow for GitHub Actions may look like this:
Metanorma provides a set of re-useable GitLab CI configurations at the
https://github.com/metanorma/ci/main/cimas-config/gitlab-ci/[`metanorma/ci`] repository (on GitHub, not GitLab).

The workflows can be reused as follows.

.`.gitlab-ci.yml` file for generating a Metanorma site and deploying it to GitLab Pages through workflow inclusion
[example]
====
[source,yml]
----
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.

.`.gitlab-ci.yml` file for generating a Metanorma site and deploying it to GitLab Pages
[example]
====
[source,yml]
----
image:
Expand All @@ -95,7 +187,6 @@ stages:
- build
- deploy


build:
stage: build
script:
Expand All @@ -122,28 +213,115 @@ pages:
- 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.

If it is suitable for you you can reuse it with the following code (to minimize code duplication):
==== 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.

.`.travis.yml` file for generating a Metanorma site
[example]
====
[source,yml]
----
include:
- remote: 'https://raw.githubusercontent.com/metanorma/ci/main/cimas-config/gitlab-ci/samples/docker.shared.yml'
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
----
====

=== Other CI providers
==== CircleCI

Generally, the integration consists of 2 phases:
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.

* link:/install[installing metanorma toolchain]
* calling metanorma-cli by shell commands
.`.circleci/config.yml` file for generating a Metanorma site
[example]
====
[source,yml]
----
version: 2.1

Most CI providers allow running CI from a Docker execution environment:
jobs:
build:
docker:
- image: metanorma/metanorma
steps:
- checkout
- run:
name: Generate Metanorma site
command: metanorma site generate --agree-to-terms

* https://docs.travis-ci.com/user/docker/[Travis CI]
* https://circleci.com/docs/using-docker/[CircleCI]
* https://www.jenkins.io/doc/book/pipeline/docker/[Jenkins]
* https://devcenter.bitrise.io/en/infrastructure/using-your-own-docker-image.html[Bitrise]
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.

.`Jenkinsfile` for generating a Metanorma site
[example]
====
[source,groovy]
----
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.

Metanorma provides a wide set of Docker images on https://hub.docker.com/r/metanorma[Docker Hub].
.`bitrise.yml` file for generating a Metanorma site
[example]
====
[source,yml]
----
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
----
====
Loading