Auto deploy your web app on GitHub

In this post we are having a look at GitHub actions and GitHub pages to build, deploy and host your static web app. Also, we are having a look at the DNS configurations to make your app available under a custom domain name. The best thing is that all of this comes for free and you only have to pay for your domain name. The result of this blogpost ist a custom subdomain (in my case http://github-deploy.zarg.es/) that links to your GitHub page which will be updated automatically when pushing changes to the main branch.

TL;DR

You can have a look at the demonstration repository that I set up here https://github.com/Zarlex/github-deploy. In order to set it up for your existing project you can do the following steps

  • Within your top level projects folder create a folder .github with the sub directory workflows

Continuous Deployment

When I started with web development in 2011, I had to build and deploy my website manually after each code change. Using an FTP client, I manually transmitted local files to a public directory on my web server. The whole process was pretty time consuming and error prone.

Luckily those days are over and we now have the tools to make the continuous deployment process happening in the background without much setup work.

Continuous deployment means that developers are writing their code and automated tests, check in their code changes into the version control system and then an automated process takes over. The process listens on changes of the version control system and and automatically runs the tests, builds the software and releases the result on the production environment.

One of the first tools that made this possible was Jenkins CI which was released in 2011. Later, Travis CI became a popular service, especially for open source projects.

And today we do not need external services because it got integrated into GitHub and is called GitHub Actions.

GitHub Actions

By providing a configuration file in your repository we can specify a workflow that shall be executed as soon as we push to a branch of our repository. Our workflow that we are going to setup contains 4 steps:

  • Checkout repository and installing dependencies

GitHub Pages

GitHub allows you to host a static website and makes it publicly available under a GitHub domain name {username}.github.io/{repo-name}. Static means that GitHub will serve a public directory with static files (html, css, js, images, …). You can not run a server with it, so no php files or whatsoever.

Furthermore, you can setup a custom domain name to use instead of the GitHub domain name.

Setup a GitHub Pages branch to publish your Web App

We are now going through the manual steps that you would do to release your web app on GitHub branches. In the next section we will automate those steps so you do not have to care about them. If you are not interested in the manual steps you can skip this section.

  1. Open your terminal and navigate to the root folder of your project. Your project has to be git repository. Make sure you have committed all changes otherwise they are lost git status.

Of course, repeating all those steps for every code change that you want to release is quite annoying and not the goal of continuous deployment. So in the next step we automate the whole procedure by using GitHub actions.

Using GitHub actions to automate the gh-pages release workflow

No we are going to setup a GitHub workflow which shall do all those steps every time we push our changes to the main branch.

  • In our top level directory of our project we create a directory .github with a subdirectory called workflows. Also we create a src folder in which we put our index.html.
Sample deployment workflow
  • In order to activate the GitHub workflow we commit all our changes and push them to our main branch.
    git add .github/ src/
    git commit -m 'Setup workflow and provide initial hello world index.html'
    git push origin main
GitHub pages release workflow is executed after pushing changes to the main branch

Enable Github pages

  1. Go to the settings page of your repo https://github.com/{username}/{repo_name}/settings/pages and enable it by selecting gh-pages as source branch and then hit the save button.
Select gh-pages as source branch to make its content publicly available

Set up a custom domain name

GitHub allows you to serve your project GitHub page from a custom domain. In this step we are setting up a custom domain name.

  1. First, you need to purchase a domain name. You can use for example gandi.net to buy one.

There are two scenarios: Apex domain or Subdomain.

Apex domain

In the first scenario our main domain points to the project GitHub page e.g. https://zarg.es. This is called Apex domain. For the Apex domain you have to configure in total 5 DNS records: 4 A records and 1 CNAME Record.
The A Records point to the GitHub server IPs and the CNAME points to our GitHub pages domain. The following shows the records we have to create. Each line is one record. Make sure to replace {username} with your GitHub username.

@ 1800 IN A 185.199.108.153
@ 1800 IN A 185.199.109.153
@ 1800 IN A 185.199.110.153
@ 1800 IN A 185.199.111.153
www 10800 IN CNAME {username}.github.io.

Thats it. However, DNS records take some time to take effect so we have to be patient and wait. Depending on the provider it can take up to 24 hours.

Subdomain

In the second scenario a subdomain points to our GitHub page e.g. https://github-deploy.zarg.es . Similar as in the first scenario we have to setup the DNS records. If not already configured we need to create the A records (same as above). Then we create a CNAME with our subdomain name. The following shows the records we have to create (if not already there). Each line is one DNS record.

@ 1800 IN A 185.199.108.153
@ 1800 IN A 185.199.109.153
@ 1800 IN A 185.199.110.153
@ 1800 IN A 185.199.111.153
github-deploy 10800 IN CNAME {username}.github.io.

Using custom domain name

In order to use our custom Apex or Subdomain name we go back to your GitHub repository and switch to the gh-pages branch. There we need to create a file called CNAME . The content of the file is our apex or subdomain domain name. In my case it is github-deploy.zarg.es

CNAME file in gh-pages branch with the domain name as content

Multi project scenario

In a multi project scenario i would create a subdomain per project

In each repository the CNAME file in the gh-pages branch would contain the domain name.

That is it. We have learned how to use GitHub actions to deploy your web app automatically, how to use GitHub pages to make you web app available to the public and how to setup DNS records for a custom domain. I hope this will help you for your further projects.

I'm a PWA developer with 7+ years of Angular experience. During the day I develop the WebApp for an IOT business application, during the night I work on aux.app