GitHub Actions and Pages
Tags: webdev, devops, node, productivity
Published: 2021-09-21 15:57:53

---
title: GitHub Actions and Pages
published: true
description: GitHub Actions has been on my radar for a while. Recently, I got a chance to work on some CI/CD operations using BitBucket and AWS. With this inspiration in mind, I started on ANOTHER new project.
tags: WebDev, DevOps, Node, Productivity
series: GitHub
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/emqq5bykpkt7hp9q4hin.png
---

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](https://www.alexhyett.com/github-actions-deploy-to-s3/) 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 ...

1. So that I can remember where I broke things when I try this again down the road.
2. 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](https://dev.to/medaminefh/how-to-host-your-static-website-with-github-85i) by [Med Amine Fh](https://dev.to/medaminefh).

It only seemed logical to look into them.

First, I started with [GitHub Pages](https://pages.github.com/) 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
<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](https://github.com/marketplace) ... I definitely need to spend more time there.

Then, I came across a [GitHub Pages action](https://github.com/marketplace/actions/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](https://github.com/marketplace/actions/github-pages-action#%EF%B8%8F-static-site-generators-with-nodejs), 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` ...

```yaml
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](https://bob-fornal.github.io/actions-test/) 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](https://github.com/bob-fornal/actions-test).