Add option for custom GitHub Pages Custom Domain

[gilesvangruisen]

Hey there! Thanks for putting this together, definitely saved me some time :)

After I got things working, I noticed the deploy worked great but my custom domain broke, as the force push overwrote the CNAME file on the pages branch.

This PR introduces a new action input github_pages_custom_domain which, when set, will ensure that a CNAME file containing that custom domain gets written and pushed to the pages source.

Thanks!

[helaili]

Thanks for this @gilesvangruisen! Can I ask you why going this way (i.e. writing code) as opposed to just adding a CNAME file to the source of your Jekyll site?

[gilesvangruisen]

@helaili Sorry for the delay! I had configured the GitHub repo settings for GH Pages, which automatically adds the CNAME file to the Pages branch. The impetus for this change was after that CNAME file was overwritten by the Jekyll deploy action.

Are you referring to the Jekyll source root or the site directory? It was unclear to me, but it makes sense, that a CNAME would be copied from site source.

It seems reasonable that codifying the CNAME like this could be clearer to users but I'm happy to abandon this if you disagree, or think that improving docs for CNAME would be a better alternative.

[helaili]

I have added a CNAME-SAMPLE in my source sample website and it gets copied to the target. I think a documentation approach is much better (and definitely needed) - less code means less bugs and less maintenance 😄

[tinacious]

I also have configured a custom domain via the repository settings, and this PR is related to this issue I just opened: https://github.com/helaili/jekyll-action/issues/46

Documentation like "Hey your custom domain will break unless you add this file" would be good as there's no clear way indicated in the docs to configure a custom domain. I can give CNAME-SAMPLE a try and see if it works.

[tinacious]

I've verified that adding a CNAME file to the repository works to retain the custom domain, and this domain setting is propagated to the repo settings page.

Considering there are multiple ways to configure your custom domain (via CNAME file as well as via the repository settings page), I think that this project should include information about this in the documentation if you prefer to not maintain code.

Either way, without explicitly stating how to work with custom domains, your action breaks sites that use custom domains that are configured via the project settings page. Adding either this code change or some documentation would be great to improve the user-friendliness of this action.

[tinacious]

I would agree that documentation would be a better approach—a code approach like this means that if I provide both a CNAME file and the configuration option, then the results could be confusing. On projects with multiple developers, this could possibly happen.

A regular Jekyll build would copy the CNAME file and then your changes would run the command echo "domain.com" > CNAME which would add a new line to the end of the existing CNAME file, having the file have 2 lines. Not sure what that would end up looking like in the repository settings but I imagine this being a source of confusion and it creating some questions like: "I added a CNAME file why isn't it working?" or "I added the config github_pages_custom_domain in the action's yaml, why isn't it working?" Probably best to use only one way (CNAME file) and specify explicitly in the docs how to use this action to support custom domains.

[gilesvangruisen]

@tinacious thanks for the comments, and sorry for the delay! I'm updating this now with documentation about adding a CNAME file.

I could be wrong, but I don't believe there's anything special with the Custom Domain setting in the Repository Settings. As far as I know, setting that field will create a file called CNAME on the selected branch, with the contents being the custom domain you entered. If you select the deployment branch, the file will be added, but this action will overwrite it on next deploy. So, the solution is either to ensure you're selecting the master or main branch when updating the Repository Settings' Custom Domain, or to create and commit the file yourself if you're running your GitHub Pages site from an alternate branch.

[helaili]

Thanks @tinacious and @gilesvangruisen. Let me know if it's ready to be merged.