As some of you know, I work on the IBM FHIR Server and with my colleagues, I have started automating some of the actions we take – Build, Test, Deploy, Deploy our website.
More specific to the “Deploy our website” automation, our website uses technologies, such as Gatsby, Carbon, Gatsby Carbon Theme. Fundamentally, a static site generation technology, like Jekyll, Gatsby uses Node, Yarn and some nice React code.
To build our site with GitHub actions, I built out a site workflow. The key elements to this workflow are:
- Triggers
- Node.js and Ubuntu Images
- Build
- Add, Commit and Push to GH Pages
- Debugging and Replicating Locally
Triggers
For the Triggers, I recommend limiting the site generation to master branches. The master branch filter and on push, limits the re-deployment, also keep your site building on on docs/** changes.
on:
push:
paths:
– “docs/**”
branches:
– master
Node.js and Ubuntu Images
I opted to use Ubuntu with Node.js
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [12.x]
The important thing is ubuntu-latest which has some incompatibility with Gatsby Carbon’s build.
Build
I build the system as follows:
Checkout the repo to a folder
steps:
-name: Grab the Master Branch
uses: actions/checkout@v1
with:
working-directory: fhir
ref: refs/heads/master
fetch-depth: 1
path: fhir
Activate Node
– name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v1
with:
node-version: ${{ matrix.node-version }}
Setup the build
echo “Check on Path”
pwd
cd docs/
npm install -g gatsby-cli
gatsby telemetry –disable
Install the packages, note, fsevents is not used on linux images, so use–no-optional (these plugins are suspect).
npm install –no-optional –save react react-copy-to-clipboard react-dom react-ga classnames carbon @carbon/addons-website carbon-components carbon-components-react carbon-addons-cloud carbon-icons gatsby gatsby-theme-carbon-starter markdown-it gatsby-plugin-manifest gatsby-plugin-slug gatsby-plugin-sitemap gatsby-plugin-sharp
so I use the suggestion as a workaround due to path/issues in the gatsby component dependency of fsevents.
npm –prefix-paths run build
cp -R public/ ../../public/
Grab the GH-Pages branch
– name: Grab the GH Pages Branch
uses: actions/checkout@v1
with:
working-directory: gh-pages
ref: refs/heads/gh-pages
fetch-depth: 1
path: docs
token: ${{ secrets.GITHUB_TOKEN }}
Per Bypassing Jekyll on GitHub Pages, be sure to add the .nojekll to the root of the gh-pages. I added a guard in the shell script to check if the file is there, and create the file if it does not exist.
If you need Environment variables, you should add the environment variables to the step.
Add, Commit and Push to GH Pages
I add the gitignore and nojekll files while removing any cached files, before moving in the new files.
I also like to make sure when this runs there is a build.txt file to trace when the site is built. (This file contains the build time Thu Nov 21 19:39:49 UTC 2019
I then use the github environment variables passed in to push the contents to the repo the branch is from.
-name: Commit and Add GH Pages
run: |
echo "cleaning up the prior files on the branch"
if [ ! -f .nojekyll ]
then
touch .nojekyll
rm -f _config.yml
fi
rm -f *.js webpack.stats.json styles-*.js styles-*.js.map webpack-runtime-*.js.map webpack-runtime-*.js manifest.webmanifest component---*.js* app-*.js*
rm -rf docs/node_modules docs/public docs/.cache
echo "Moving the files around for gh-pages"
cp -Rf ../public/* ./
find .
date > build.txt
git config --global user.email "${{ secrets.GITHUB_ACTOR }}@users.noreply.github.com"
git config --global user.name "Git Hub Site Automation"
git add .
git commit -m "Update to GH-Pages"
- name: Push changes to GH Pages
run: |
echo "Push Changes"
git branch
remote_repo="https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
git push "${remote_repo}" HEAD:gh-pages
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GITHUB_REPOSITORY: ${{ secrets.GITHUB_REPOSITORY }}
GITHUB_ACTOR: ${{ secrets.GITHUB_ACTOR }}
CI: true
Debugging and Replicating Locally
If you are troubleshooting, you can use a couple of approaches:
1 – Create a Docker Image
Create the Image
docker run -itd –name gatsby-node -v docs:/data node:latest
Copy the Files
docker cp ~/FHIR/docs 6d810efb3b586739932166d424641003ee9b238de506543fcdd47eb7e7d41699:/data
Launch the shell and try the build
npm install –no-optional –save react react-copy-to-clipboard react-dom react-ga classnames carbon @carbon/addons-website carbon-components carbon-components-react carbon-addons-cloud carbon-icons gatsby gatsby-theme-carbon-starter markdown-it gatsby-plugin-manifest gatsby-plugin-slug gatsby-plugin-sitemap gatsby-plugin-sharp
Run the gatsby build
npm –prefix-paths run build
2. If you want complicated navigation, refer to https://github.com/gatsbyjs/gatsby/blob/master/www/src/data/sidebars/doc-links.yaml however… gatsby-carbon-theme’s sidebar links only uses the to value not the href value.
3. If you have an issue with your deployment check a couple of things:
Check your Deployed Environment. You should see a deployment in the last few seconds.
Check your Settings You should see no issues, else investigate the site locally on the gh-pages branch, and check Troubleshooting Jekyll build errors for GitHub Pages sites
Best of luck with your build!
