Frontend dummie: how to set up a simple CI/CD for your personal app with GitHub actions and GitHub pages
I admit, it is super intimidating as a self-taught frontender to hear the words “CI/CD”, “deployment”, etc etc. It sounds far away and way too tech-y, at least for me, and it makes me feel excluded whenever we are touching the topic.
The idea that I don’t know about something is itchy, and it eventually hit me someday when I tried to have a live page for a project I created — of course, I want it to be deployed every time I push. This is almost a no-brainer in any company. It is always there for me without me thinking. However, now I need to do it myself.
I plan to do it as simple as possible, as I only want to taste the blood of victory. So I decide to deploy the app on GitHub pages, and use GitHub action to setup the pipeline.
Preparation
Create a GitHub repository and get the cloning URL. Clone the empty repo, create a html page with ‘Hello world’ in a div and do npm init -y , so you have a project to start out. Now you can do an initial commit.
For framework users (React, Vue, Angular etc), bootstrap your project and do an initial commit.
GitHub pages
For those who don’t know about GitHub pages, it is a tool to generate a static page from your GitHub repository and host it.
To enable GitHub pages:
- go to settings in the repo
- scroll down to ‘GitHub pages’
- choose master branch in source drop down menu
An URL is generated in the GitHub pages section like so: https://yourname.github.io/yourproject/. Voila! Your app is live now! Go to that address, you should see your ‘Hello world’ printing on the screen.
For framework users, one more step is needed to enable a simple deployment if you do not want to manually build and configure the publish. (You do not need to do this if you go directly with setting up CD.)
Install a package npm install -D gh-pages , and add the following scripts to your package.json (You can also find on their doc):
"scripts": {
...
"predeploy": "npm run build",
"deploy": "gh-pages -d build"
}Up till now, we managed to deploy our app. For the simple case (only HTML page), every time you change something, it will reflect in the deployed URL. However, for the app made with framework, you will soon realize it does not pick up the new changes. The reason is that the way gh-pages works is to create a branch with the same name and push the built static files into that branch; every time you change something, you will need to re build and push (or run npm run deploy ) to update the static files so the deployed app can be refreshed as well.
That’s exactly why we need a CD pipeline here so we do not need to do the manual work.
GitHub Actions
For whose who hasn’t heard about or used GitHub actions:
“GitHub Actions is an API for cause and effect on GitHub: orchestrate any workflow, based on any event, while GitHub manages the execution, provides rich feedback, and secures every step along the way. With GitHub Actions, workflows and steps are just code in a repository, so you can create, share, reuse, and fork your software development practices.”
In short, we could write a workflow and GitHub will take care of the rest for us, and it is not just CI/CD, and it covers virtually everything GitHub offers.
Here we only care about setting up a pipeline to deploy. As a frontend dummie, I do not understand much about docker containers, Kubernetes etc, but I know how to find tools to achieve my immediate goal. So here we will only use a ready tool to help accomplish complex task.
I’ve found this action in GitHub actions marketplace which puts everything into a black box. If you want to understand more, go into their documentation and it’s pretty extensive. Now go ahead and create a yaml file like so:
// .github/workflows/github-page.yml
name: deploy to github page
on:
push:
branches:
- master # meaning pushing to master will trigger the action
jobs: # can include multiple jobs
deploy: # here we will only have deploy
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2 # an action checkout your repo
- run: |
npm install
npm run build #first run these two scripts- name: Deploy
uses: peaceiris/actions-gh-pages@v3 # this is the magic
with:
github_token: ${{ secrets.GITHUB_TOKEN }} # GitHub Actions runner automatically creates a GITHUB_TOKEN secret to use in your workflow
publish_dir: ./build
Push this file plus some visual change that you could use to verify.
Go to Actions tab in your repo and take a look at action running.
The almost matrix-look screen basically is showing the steps of running script you just set up in the workflow: it checks out to the repo, then it does npm install and npm run build , finally it does the black magic with the github page actions. The cool thing is that from now on, every time you push some thing to master , this workflow will be triggered and new change will be deployed. Welcome to the world of automation!
At the end, congratulations, you’ve just set your first CD pipeline!
References
Friedman N. (2019). GitHub Actions now supports CI/CD, free for public repositories. Retrieved from https://github.blog/2019-08-08-github-actions-now-supports-ci-cd/
I’ve started this initiative recently, to write about dummie article of how I learn new things. It’s gonna be very beginner friendly as by the time I wrote the article, I just came from an absolute beginner. Follow through this fun and scary journey!
I’m Zoey Zou, currently a front-end web developer based in Copenhagen. I write about stuff, so random that I cannot conclude. I organize meetups and workshops with friends too. I have a very bizarre style of emcee and I love to see people awkward but happy at the same time.
If you want to connect with me:
twitter: @zoeyzou0117
linkedin: https://www.linkedin.com/in/zoeyzou2018/
github: @zoeyzou
