GitHub Pages for Astro Project — Deploying from Branch vs Using GitHub Actions

GitHub Pages is a simple and direct way to deploy your web projects to the internet. While it provides an option to directly Deploy from a Branch with built-in support for static site rendering, GitHub also provides an option to customise your deployment workflow through GitHub Actions, to allow room for integrations of your own — and in my case, the use of Astro and certain JS libraries. Given the case, which workflow is better for an Astro project?

TL;DR

While Deploy from a Branch provides inbuilt support for Jekyll to host your website with pre-customised options with ease, GitHub Actions can be used when this deployment process needs to be configured according to the project’s needs. When additional libraries are used by integrating with Astro, it requires many additional modifications. Thus, it is preferred to use GitHub Actions to be able to customise workflows with ease.

During my internship at VLEAD, Virtual Labs, I was part of a team responsible for redesigning and deploying their website. We chose to build the website using Astro. Astro being a relatively new framework for us, we faced certain issues in its deployment on GitHub pages. This blog here is our journey through the deployment and describes the issues we faced through the process.

There are two ways to deploy your code through GitHub Pages — GitHub Actions, and Deploy From a Branch.

Deploying From a Branch — Jekyll Site

Deploy From a Branch method inherently integrates Jekyll to create a static site. Jekyll and Astro, however, disagree on one primary instance — Jekyll does not recognise files with names starting with an underscore; Astro conventionally names its build files starting with an underscore.
To address this difference, you are required to create .nojekyll files in the project directory, and customise the build:assets naming to “astro” instead of “_astro” in the astro.config.mjs file. The complete steps can be found here — link.

This method however, failed for us. We used Typewriter-effect, a JS library, as part of our website. This library also creates its build file named starting with underscore. The above solution however, handles the naming of only Astro build file, and not the individual integrations. Thus, it is not a permanent solution that lets you incorporate all different libraries and packages you want to use. And which is why, in case of frameworks like Astro, it is advisable to use GitHub Actions for deployment.

Using GitHub Actions

GitHub Actions provides more flexibility and control over the entire deployment process. There might be more such cases where you need more customisation, such as deploying the site to a different hosting service, performing additional build steps, or integrating with other services before or after deployment. In such cases, you can use GitHub Actions to create custom workflows that suit your specific deployment needs.

This method does not by default integrate with Jekyll, thus removing the naming convention problem totally.

Using GitHub Actions requires creating a YAML file with required customisation to the deployment. For Astro, the complete process can be found in the Astro documentation here — link.

GitHub Actions is a more modern method; many frameworks already provide Actions like in Astro to implement in the deployment. They can be used directly without worrying about their maintenance, and generally cover all aspects of deployment required for a good level project.

Thus, by using GitHub Actions in this manner, you can customise the deployment process for your Astro project. So go ahead and deploy your Astro project on GitHub and see your website come live on the internet!