For a while I've wanted to dig into GitHub Actions. It's been something on my radar for about a year.

Recently, while hacking on a side-project, I got a chance to work on some CI/CD operations using BitBucket and AWS S3 as a website. As a side note, I did find an awesome article on deploying from GitHub to AWS S3.

With all this inspiration in mind, I started on ANOTHER new project.

While I'm thinking of it, let me say that this is an article about my journey ...

So that I can remember where I broke things when I try this again down the road.
So that I hopefully give someone some information and maybe even encourage some exploration.

GitHub Pages

As I started this project I wanted to look at using GitHub Pages. I've seen several articles on them, including How To Host your static website with Github by Med Amine Fh.

It only seemed logical to look into them.

First, I started with GitHub Pages and realized that I had options:

A User or Organization Site
A Project Site

Not being sure what I was looking at, I read through both sets of instructions and found out that ...

The User or Organization Site lead to https://username.github.io and
The Project Site was at https://username.github.io/repository

... this showed me that I wanted to play with the second option, generating a static site against a single repository.

So, following the directions, I created a repository named actions-test which seemed to describe the direction I wanted to go.

Following the directions, I created the repository and manually entered the following as index.html on the site.

<html>
  <head></head>
  <body>
    <h1>Hello World!</html>
  <body>
</html>

I know ... not too creative; I just wanted to see if it would work.

Then, I headed to the Settings > Pages and set the Source to Branch: main and / (root). Once I saved, a message showed that it was getting ready to publish the repository. After refreshing a few times, the message indicated the site was published and I followed the link to see my amazing site.

GitHub Actions

Now that I had proved I could get this to work, I headed out to find some actions that would allow me to push code and have the CI/CD pipeline generate the Page!

One of the first things I found was the GitHub Marketplace ... I definitely need to spend more time there.

Then, I came across a GitHub Pages action in the Marketplace. There were actually a few ... I selected this one based on number of follower and frequency of code deployment.

There are quite a few ways this code can be used in the documentation; I settled on Static Site Generators with Node.js, remembering an old project I built using NodeJS to generate a rough page ... this gave me something a bit more exciting than the HTML above.

My next step was to create the YAML file. I had clicked the "Use latest version" button at the top and had the code to ensure I was using the correct version. Then, I followed the link above and quickly built the file at .github/workflows/gh-pages.yml ...

name: GitHub Pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v2

      - name: Setup Node
        uses: actions/setup-node@v2
        with:
          node-version: '14'

      - name: Cache dependencies
        uses: actions/cache@v2
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-
      - run: npm ci
      - run: npm run build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3.7.3
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

I'm not going to go into a detailed explanation of the code above ... pretty sure I understand just enough. I saw that it's using Node 14, that npm ci, and npm run build. And, while I had to learn what npm ci does, it all was pretty straight forward.

Since the old project I wanted to use invoked npm run build to generate the final code, all of my changes wound up being in the last part of this code. I changed ...

The uses line to match the latest version
The publish_dir line to match the dist folder my code generated.

The Results

Having put all this code together with a copy of all my old project code, I pushed ... to watch the Actions, workflow runs (if you were to look at my repository, you'll see that I pushed a version before saving the YAML file and watched it fail).

Very quickly I had something building. I had to manually set the Settings > Pages and set the Source to Branch: gh-pages and / (root) ... this branch was created by the action code above with the contents of the dist folder described.

After all this excitement I clicked on the link ...

The Failure

... to see a 404 page (spend any time on GitHub and you know what I was looking at.

To make a long story (waiting, refreshing, and searching on my part) short, I found out that my HTML needed a <!DOCTYPE html> tag. Without that tag, the page didn't display.

Summary

The process of generating my STATIC REPOSITORY PAGE was pretty straight forward. This was a fun and rewarding experiment ... there's something satisfying when you see the pipeline run and do something expected, knowing you can repeat this pattern any time and any number of times to get things right.

I'm absolutely sure I've got more to learn and more articles to write ... for now, here's the REPO.

GitHub Actions and Pages

GitHub Pages

GitHub Actions

The Results

The Failure

Summary