Resources to better understand Github Actions?

Help
1

I’m having a difficult time grasping what exactly Github Actions are, what they do, and how to tell when the action has succeeded. I’ve read the docs on jekyllrb and Github but I’m still a deer in headlights for some reason.

I’m currently utilizing (I think?) this action https://github.com/jeffreytse/jekyll-deploy-action, recommended by my theme author. However, I recently started using (again, I think?) this action https://github.com/MichaelCurrin/jekyll-gh-actions-quickstart/blob/main/.github/workflows/main.yml, and to be honest, I can’t tell the difference between the two, or even the difference from not using one at all.

If there exists a resource that explains it in layman’s terms, I’d be very interested.

2

I am learning GitHub Actions right now and have had a developer help me through the first two, which was a terrific learning experience. I plan to create a short videos series on this, but allow me to share what I believe to be accurate at a high-level (anyone can politely correct me if I am wrong):

GitHub Actions runs activities you define. They run based on triggers that can be based on things like:

  • When someone closes an issue
  • When code is pushed to a specified branch
  • At a specific time of day, based on a CRON job
  • When a human being runs the action manually

:person_raising_hand:How do GitHub Actions run?

GitHub Actions is not much more than a file that instructs GitHub to run commands you define. It will run those things based on triggers (more on that in a minute). It will also open up a virtual environment (ubuntu, Mac, Windows, etc.).

You usually instruct GitHub Action to place a Docker image inside that virtual environment.

:package: Docker images and containers

Docker is essentially a technology that allows you to run a trimmed-down operating system without going through the hassle of installing the whole OS each time. Docker containers can come with pre-installed software to make it easier for you to get started. You start with an image and then build a container from that image.

I created a video that shows you how to build Jekyll in a container on your computer without having to install Ruby or Jekyll on your computer. Here is the video that might be a good start for you:

Imagine you just purchased a computer with nothing on it. You install Linux and Ruby on it. Because you want a nice clean copy just in case you mess it up, you make a backup of your computer. Think of that backup as your image.

On that same computer, you install other apps, like Jekyll, Python, Git, Imagemagick, and other tools. You may also need to run certain scripts and commands. Think of that as your container.

So your container is a copy of an image and then you can mess around in it without ever ruining the original image.

:arrow_right_hook: Workflow process

In general, you can look at GitHub actions as a workflow that looks something like this:

  1. Runs a file in the ./.github/workflows folder based on a trigger and runs a YAML file, like buildjekyll.yml

  2. The YAML file Instruct the workflow to open a virtual environment and open a Dockerfile

  3. When the Dockerfile runs, it retrieves an image from a Docker repository. In my case, I use an official Ruby image that is available from the official Docker Repository (sort of an app store for images)

  4. The Dockerfile can then run a script, which often points to ./entrypoint.sh

  5. The script usually does all the “real” things you want to do with your GitHub action. Since you are basically in a shell command, you can do pretty much anything you need to. For example, it can build your Jekyll site and then copy it to another branch or another repo.

So it sort of goes like this workflow_file.yml > Dockerfile > Entrypoint.sh [optionally] > other script files

:earth_asia: Real-world example

As of this writing, I have a GitHub Repo that contains my Jekyll 4.x code. GitHub Pages only support 3.9.x. However, GitHub Pages is just a web server, so it will always display standard HTML and CSS.

As I am sure you know, when you build a Jekyll site, it outputs industry-standard HTML and CSS. Those resultant files are no longer Jekyll, so GitHub Pages will happily display them.

I have a GitHub Action that opens my code repo, builds the Jekyll website, copies the files, and puts them into a second Website Repo where GitHub Pages is enabled, and my Agile in Action website automatically updates.

Also, I use ImageMagick to build featured images for every post. It creates a nice image that displays the name of the podcast and a picture of the guests. Since it can be very slow to use ImageMagick locally, my entrypoint file not only builds and builds and copies the Jekyll site, it runs a Python script that uses ImageMagick to build the featured images for every post.

I have a file called push.yml in my .github/workflows folder. The workflow opens my Dockerfile, which instructs it to get a Docker image based on Ruby (required for Jekyll) and the Alpine Linux variant (because it is small and fast). The Dockerfile contains instructions to build a Docker container from an image and install Jekyll, Python, and ImageMagick.

At the end of my Dockerfile code, I have a line that says run enterypoint.sh. That sh extension means “shell”.

In my case, my entrypoint is a BASH shell script that runs the ImageMagick Python script, builds the Jekyll site, then copies the changed website files over to my GitHub website repo. Once complete, my website is up to date!

:money_with_wings: Pricing and consumption

Now that you know a GitHub Action is pretty much anything you can imagine doing in a command line, including installing and using other software products, GitHub cannot assume your use case.

For example, I doubt the GitHub team ever sat around in a room and assumed I would install Python and ImageMagick on my site to build featured images.

For that reason, GitHub says, “Do what you want, but with limitations on how long you do it”. Note that GitHub Actions are also called CI/CD (continuous improvement/continuous development).

As of this writing, the GitHub free tier allows you up to 2,000 CI/CD minutes a month.

When I go to the GitHub Actions page, I can see my workflow takes approximately 5 minutes. Here are my approximate numbers:

Automatic daily build: 5 minutes/day * 30 days = 150 minutes
Code pushes (usually new podcast posts): 4 updates/week * 5 minutes * 4 weeks = 80 minutes
Total usage: 230 minutes/month out of a possible 2,000 minutes/month

:deciduous_tree: Earth consciousness

Late last year, my GitHub Action was very inefficient. ImageMagick would rebuild every featured image for every post. Also, the Docker container took a long time to install the components I required.

Every GitHub Action run took 20 minutes, which is 920 minutes/month. Worrying about my carbon footprint, I made two significant changes:

  1. Build with a Docker image that is small, compact, and fast (Ruby Alpine)
  2. Adjust my ImageMagick scripts to only work with new posts, not older ones

With those small changes, I saved 8,280 worth of computing minutes per year :tada:. Every little bit counts!

:warning: About pre-built GitHub Actions

I find people use pre-built GitHub Actions and do not know how they work. For example, you might find a great GitHub Action that builds your Jekyll site. But does the action do anything else? Was it designed a long time ago, and are there better methods? I highly recommend you minimally learn Docker and shells like BASH and ZSH so you can read what the workflow does before putting it into production.

I know the pre-built GitHub actions you are using are from reputable sources, so please do not take my comments to say that you are doing anything wrong. It is more of a word of warning.

:bulb: Looking for ideas

I hope that helps and if there is anything you want me to put into a training video, please let me know because I am sketching them at the moment.

:hugs: If I am wrong about any of this, please be nice. I am not an expert

4 Likes
3

I appreciate your response, thank you! I run my jekyll environment in a Ubuntu instance via wsl 2 and briefly tested with docker images in the past, which I ultimately decided just complicated things without adding any benefit, yet I still don’t understand the use case of either of the two previously referenced premade deploy actions, or how to and why I would need to write my own.

I believe I know what these actions are supposed to do; instruct GH to virtualize the building and deployment of a jekyll site identically to how it would be built on the users local machine. I understand that this is most often used so that production on gh can run the same jekyll version as the local machine, and thus build the site without inconsistencies between the two. But there’s still so much about the process I don’t get, or don’t get the reason for, that is frustrating.

I have yet to conceptually understand why docker is necessary in this ‘workflow’, and I still can’t visually pickup on any difference in the production site with or without a gh action. I guess since I haven’t had an issue with deployment without a gh action, even without adhering to the whitelisted plugins or proper jekyll version, despite that being apparently impossible (and thus I am obviously missing something(s)), coupled with being incapable of visually determining any difference or benefit to the site after using a gh action or not, and not being able to follow the ‘workflow’ while the building/deployment is in process on gh, I should just not use them.

Will definitely watch your video. I’ve already been using your Up and Running series for reference after I had read some of your rich comments here. Again, thank you, and hopefully I’ll stumble across some sort of step by step explanatory work to break down the use case of actions within the framework of a jekyll site on github using jekyll 4. If anyone is aware of a reference work like this, please let me know. First things first, google the definition of workflow and the phrase at scale, because after months of tinkering with front end web dev my brain breaks every time I hear either of those terms which is becoming increasingly more frequent thanks to personalized ads.

4

I think you have the basics down. The primary reason for using a GitHub Action is because you want to build a Jekyll site that uses unsupported GitHub Pages dependencies. Or, maybe you want to build a Next.js or Hugo site. Those would also be good use cases.

The reason you use the Docker container is because that is the place where you run your scripts to build Jekyll.

If I am not wrong, the Ubuntu environment you create with your GitHub Action YAML file is just a platform on which you can run your Docker container (even if the Docker container is Ubuntu itself).

As for videos or articles, I watched so many and they skip over these details. If I stumble across one, I will let you know. When I create the video, I will share it with you.

I am glad the other videos are helping you.

2 Likes