Auto deploy your web app on GitHub

7 min readApr 30, 2021

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
Place the file deploy.yml in order to setup the GitHub workflow
Copy and paste the boiler plate from here and adjust the build instructions under Install and Build > run
Activate GitHub Pages in order to allow public access of your deployment. Go to https://github.com/{username}/{repo_name}/settings/pages and select gh-pages as source branch

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
Run automated tests
Build software (e.g. compile TypeScript to JavaScript, minify and obfuscate JavaScript code, build SASS to CSS, minify images,…)
Deploy result to GitHub Pages

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.

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.
Create an orphan gh-pages branch. Orphan means that the branch is not related to your main branch anymore so it has its own version history.
git checkout — orphan gh-pages
Remove all files in it and stage the changes.
rm -rf ./
git add --updateThe option --update makes sure that all updates will be staged but not untracked file as the option --all would do.
Create an index.html file with some content
Commit file and push it to your repository
git add index.html git commit -m 'Initial deploy commit' git push origin gh-pages
Go back to the main branch and reset it to the previous state
git checkout main git reset --hard origin main

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.
In the workflows directory we place a file called deploy.yml (you can also give it a different name). In this file we define our workflow. The file configures for which branch the workflow shall be executed and then the steps that shall be executed.
Our first step is Checkout, which checks out test latest master revision
The second step Build, builds the app. For demonstration purposes, we simply just copy all files from src to dist. Of course you can also do more sophisticated stuff here like bundling your JavaScript files, compile SCSS files to CSS and so on. Also before building your app you should run the automated tests. However, as we only have a simple app for this blog post, testing it is out of scope.
Last but not least we have the Deploy step, were we publish our app on GitHub Pages (the steps that we did in the manual part of this post). Luckily, we do not have to write anything for that but can just use an available action provided by JamesIves

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
You can go the actions tab of you repository where you can now see your workflow being executed
That is it! Now, every time you push something to the main branch it will be automatically deployed and becomes publicly available under you gh-pages url.

GitHub pages release workflow is executed after pushing changes to the main branch

Enable Github pages

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.
GitHub shows a message that your gh-pages branch file content is now publicly available https://{username}.github.io/{repo-name} Open the link and you will see the content of the index.html

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.

First, you need to purchase a domain name. You can use for example gandi.net to buy one.
Then you have to add new DNS records.

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.