Metanorma document setup sample: Automatic deploys to GitHub Pages using GitHub Actions

Introduction

This repository demonstrates how to setup a Metanorma document repository to achieve:

• continuous integration document building

• automatic deployment to GitHub pages

Usage

1. Generate a public/private keypair using ssh-keygen (see Create a GitHub per-repository deploy key)

2. Define GH_DEPLOY_KEY as deployment key in GitHub repository settings

3. Copy the necessary files to your own Metanorma document repository.

General structure

metanorma.yml

The configuration file used to control execution behavior. You might want to set the following variables:

metanorma.deploy.email

the email that makes the commit to gh-pages; set to ci@metanorma.org by default.

relaton

you will need to set these if you are deploying a document collection. Specifically, set these:

relaton:
  collection:
    organization: "TODO: Fill in authoring organization"
    name: "TODO: Fill in document collection name"

Makefile

provides methods to:

1. build the document (make clean, make all); and

2. setup and move artifacts into the published/ directory for deployment (make publish).

.github/workflows/docker.yml

GitHub Actions configuration file which provides the dedicated job called deploy-gh-pages for GitHub Pages deployment on master update

1. build the document via make; and

2. deploy the document using the peaceiris/actions-gh-pages@v3 action from https://github.com/marketplace/actions/github-pages-action];

peaceiris/actions-gh-pages@v3

is an action referenced in .github/workflows/docker.yml used to upload published artifacts to GitHub pages automatically:

1. decrypting the GitHub per-repository deploy key used to push the compiled output to the GitHub repository itself;

2. pushing the “published” files (created in the published/ directory by make publish) to the GitHub repository’s gh-pages branch.

Detailed instructions

Install necessary files into your repository

Depending on your setup you may want to copy some or all of the files provided.

• metanorma.yml

• Makefile

• .github/workflows/docker.yml

Note	Please don’t change the file contents unless you know what you’re doing.

1. If you use a SINGLE REPO FOR YOUR DOCUMENT:
   

   cd {my-metanorma-document-repository}
   curl https://raw.githubusercontent.com/metanorma/metanorma-cli/master/templates/base/metanorma.yml --output metanorma.yml
   curl https://raw.githubusercontent.com/metanorma/metanorma-cli/master/templates/base/Makefile --output Makefile
   curl https://raw.githubusercontent.com/metanorma/metanorma-cli/master/templates/base/.github/workflows/docker.yml --output .github/workflows/docker.yml --create-dirs

   Note	See the example from CalConnect’s VPOLL document.

And commit these files:

git add metanorma.yml Makefile .github/workflows/docker.yml
git commit -m 'Setup deploy scripts and variables for GitHub Actions'
git push

Create a GitHub per-repository deploy key

1. Generate a SSH keypair using ssh-keygen
   

   export DEPLOY_EMAIL=ci@metanorma.org
   ssh-keygen -t rsa -b 4096 -N '' -C "${DEPLOY_EMAIL}" -f ./deploy_key

   The public key of the deploy key will be located at ./deploy_key.pub

2. Go to your GitHub repository page, “Settings”, then “Deploy keys”.

3. Click “Add deploy key”

   1. Title: “GitHub Actions deployment to gh-pages”

   2. Key: copy and paste the content from ./deploy_key.pub

   3. Tick “Allow write access” to allow this key to push to the gh-pages branch

Done and profit!

Yay!

Credits

The Metanorma project from Ribose Open.