Static Website Hosting on Github - Part 2

In part one we covered off hosting a static website using GitHub pages and identified some limitations in the basic approach when compared to hosting on Azure as a static web app with Github Actions automation via the Azure/static-web-apps-deploy Action.

Now we will explore our options to improve the process.

TL;DR - This is going to run to a part 3 , as I don’t like this method!

Manual Method Using Git Submodule

A git submodule is typically used where you have a third-party library or dependency within your base project.

In our case, we could treat the public folder as a Git submodule (this is where Hugo builds/compiles the site), thus divert the complied code to a separate repo than the source code. If you want to read up on Git Submodules here’s the link

Here is a flow diagram that should help explain the result:

graph TD A[Start] -->|Update Website and Build locally| B(git push x2) B --> C{Path in base project?} C -->|Yes| D(Push to Source Code Repo1) C -->|No-Submodule| E(Push to Compiled Code Repo2) E -->|Repo2 Pages Action| F(Deploy to Github Pages) D -->|No Actions| G[End] F --> G

Assuming you start from the base folder of your website (e.g. my-new-blog in our previous examples)

# Make our GITHUBUSERNAME.github.io repo a submodule of our Hugo source repo
# Run from the base of the blog site folder e.g. my-blog-site

# recursively remove any existing public folder
rm -rf public

# clone the compiled code to a new public folder using a mac (ssh auth)
#git submodule add git@github.com:GITHUBUSERNAME/GITHUBUSERNAME.github.io.git public

# clone the compiled code to a new public folder using windows (http)
git submodule add https://github.com/GITHUBUSERNAME/GITHUBUSERNAME.github.io.git public

As I had an existing build in the (now submodule) origin repo this command pulled down that content, as it impies a ‘git submodule init’ and a ‘git submodule update’.

I then ran:

# build site from latest source files, will overwrite existing contents of public
hugo
git add .                             # add any new files in base project
git commit -a -m "push source files"  # commit source files, including ammended
git push

It’s worth noting the actions above don’t imply a commit on the submodule, at this point my /public folder is still showing untracked via a ‘git status’. So we basically have do the same for our submodule:

cd public
git add .                            # add any new build files
git commit -a -m "push build files"  # commit build files, including ammended
git push

Your latest site updates should be live in a few minutes and your source code stored in Github. Your source code repo can be private, but the build repo with the pages action has to be public (outside of a Github Enterprise licence). So having a public submodule in a private repo is no issue.

Incidentally

Would you be interested in a blog series on git from the perspective of non-developers? let me know in the comments below.

Method Thoughts

I have no intention of compiling the code, then updating the search index etc locally, as such this is entirely unsatisfactory to me, but it works and I worked it through and document it here for completeness plus raise awareness of the benefit of our final solution!

If you used this method you would obviously script all these steps together into a standardised workflow, plus add all the manual index updates steps etc. But isn’t running a batchfile on your local machine a bit 90’s?

Do you agree? If not you’re all set, otherwise onto part 3

thedevopscat blog

Static Website Hosting on Github - Part 2

Table of Contents

Manual Method Using Git Submodule

Incidentally

Method Thoughts