Automate Cryogen Clojure blog with GitHub Actions
Practicalli uses Cryogen static site generator for its blog website. Cryogen is fast and simple to use thanks to the Clojure EDN file used for configuration.
Cryogen documentation shows how to publish a Cryogen blog to GitHub pages using Git command. The deployment can be automated using GitHub actions, so that a new version of the site is deployed when Pull Requests are merged to the specified branch (or on direct commits to that branch).
What does the GitHub workflow do?λ︎
This is a combination of GitHub actions, each doing a specific part of the automated workflow.
The publish job runs on an Ubuntu docker image and the Checkout step performs a git checkout of the project into the docker image.
Prepare Java step uses the setup-java action to add Java 11 to the docker image, using the Eclipse Foundation temurin image
OpenJDK manged by Eclipse Foundation
OpenJDK / AdoptOpenJDK is now part of the Eclipse Foundation).
Install clojure tools step uses the setup-clojure action to add the specified version of Clojure CLI tools (Leiningen and Boot build tools are also supported)
Build blog site step calls the Cryogen function using Clojure CLI tools to build the static site
Publish to GitHub pages step uses the github-pages-deploy-action to deploy a specific directory, the directory built by Cryogen, to another branch of the original repository or a different repository. If the branch does not exist, the action will create it.
Deploying to other repositoriesλ︎
When deploying the Cryogen site to the same GitHub repository as the source files, the github-pages-deploy-action does not require an explicit token to be added. The action uses the default repository scoped GitHub token.
If deploying the site to another repository from that of its source files, create a GitHub secret with a value of a Personal Access Token (PAT). The personal access token should have the least permissions necessary, usually only repo.
A GitHub secret can be added at user or organisation level and configured for specific repositories.
Add GitHub Actionλ︎
Create a file called .github/workflows/cryogen-publish.yml and add a workflow configuration.
name: Publish Blog
on:
push:
branches:
- live
jobs:
publish:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Prepare java
uses: actions/setup-java@v2
with:
distribution: 'temurin'
java-version: '11'
- name: Install clojure tools
uses: DeLaGuardo/setup-clojure@3.5
with:
cli: 1.10.3.943
- name: Build Blog site
run: clojure -M:build
- name: Publish to GitHub Pages
uses: JamesIves/github-pages-deploy-action@4.1.4
with:
commit-message: ${{ github.event.head_commit.message }}
branch: gh-pages # branch to deploy to
single-commit: yes # no commit history
folder: public/blog # directory to deploy from
GitHub Action configuration with tokenλ︎
If deploying to a different repository than the source, then add a token to either a repository, account or organisation secret. Use a GitHub Personal Access Token for the value of the token secret.
- name: Publish to GitHub Pages
uses: JamesIves/github-pages-deploy-action@4.1.4
with:
commit-message: ${{ github.event.head_commit.message }}
token: ${{ secrets.PRACTICALLI_BLOG_PUBLISH_TOKEN }} # GitHub secret
repository-name: practicalli/deployed-blog # repository to deploy to
branch: gh-pages # branch to deploy to
single-commit: yes # no commit history
folder: public/blog # directory to deploy from
Deploying to AWS S3 bucketλ︎
Cryogen can also be published to an Amazon S3 bucket by taking the above GitHub action and replacing the Publish to GitHub Pages step.
Add the following step in its place and add GitHub secrets to the Git Repository for AWS access and the name of the AWS bucket.
- name: Publish to AWS S3
uses: jakejarvis/s3-sync-action@master
with:
args: --follow-symlinks --delete --acl public-read
env:
AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
AWS_REGION: 'eu-west-2'
SOURCE_DIR: 'public/blog'
NOTE: also check the AWS region is the correct one for your needs
Summaryλ︎
Once the .github/workflows/cryogent-publish.yml file is committed to the default branch of the repository, any commits to that branch or merged pull requests to that branch will trigger the workflow and publish a new version of the Cryogen static website.
Consider adding linters and other GitHub Actions to check for potential issues with markdown and other aspects of the website, to avoid checking in content that may break the website.
Setting up monitoring of the website is also recommended, using simple monitoring tools such as StatusCake.
Thank you.
Practical.li Website