Hosting on Github: Why github actions needed?

support
1

Hello,

if I understand the docs correctly (which I find very very hard to grasp) Host on GitHub | Hugo we have two directories in the case of user pages: one for the sources and one for the public folder. We also have github actions that build from source into public.

Now I’m wondering: If we already split everything up into two repos, why would we need github actions? We’d have to locally build and commit the new static files anyway. So what’s the point?

2

Hi @xotix. I hope we can sort this out :wink: Right now you are throwing all the term into one box, mix them up and come out confused on the other side. You either don’t understand, how Hugo works OR you don’t understand how HOSTING (having a website online) on Github works.

Hugo runs and creates the website from your source (that can be in one repository or many, Hugo can understands it all, but again, I don’t see two repositories involved in the docs) and puts it into a public folder. From there the website must be deployed to where it is hosted. The repository and the public folder are NOT the “Hosting on Github”.

On Github you receive a publicly available website if you host the site in a branch called gh_pages. Github puts that whole branch up as website.

What the action in the documentation does is understanding that there is new content, then running Hugo and moving the resulting files into that location where Github deploys them as a website.

As in:

Repo: GitHub - github/government.github.com: Gather, curate, and feature stories of public servants and civic hackers using GitHub as part of their open government innovations
Website: https://government.github.com/

So, as far as I see there are not two repos :wink: There is your Hugo repo and then the branch within that gets deployed on Github, AFTER you push changes to it.

3

So your answer actually just added to my confusion since it seems to me that you actually disagree with hugo’s documentation. Let me go through it again in detail, so you can point out where I went wrong.

To quote github’s docs: About GitHub Pages - GitHub Docs

If the default publishing source exists in your repository, GitHub Pages will automatically publish a site from that source. The default publishing source for user and organization sites is the root of the default branch for the repository. The default publishing source for project sites is the root of the gh-pages branch.

Now I made a github page using username dot github dot io by creating a repository called username dot github dot io. So from the above quote I conclude: publishing is done from the root of the default branch. In my case, that’s master (opposed to main which is by default used on github.)

Now the docs of hugo say: Host on GitHub Pages | Hugo

Content from the main branch will be used to publish your GitHub Pages site

whereas, again, we create a user github page.

So now you have the following situation: You have the source files in / and the generated static files in /public. /public is what is being served by your webserver i.e. what is being hosted. Now, from both quotes above we know that the default branch is being served but now, since we only have on repo, the default branch contains / and not /public.

So github tries to served everything.

I then assumed that hugo uses the action to A) generate the static files after a push B) tell github pages “served /public folder”.

After googling a lot and everyone seeming to use two repos I opted for that and concluded: I don’t understand the hugo docs.

Especially because of this

This is a much simpler setup as your Hugo files and generated content are published into two different repositories.

I read that as “The above setup is much simple because we divide hosted files and source into two repos”. The whole sentences is confusing not only because of the formulation but also because we didn’t even set up anything, we just discussed stuff.

Question:

  1. Why do you think that gh_pages is being served for a user github page when the docs clearly state the default branch is being served?
  2. Assuming 1. is correct and I want to use one repository. How should that be possible to set up?

Edit: How come a new user can’t post infinite links. :stuck_out_tongue: the “dot” in the links means “.”

Currently I’d solve it like this: 1 repo with a master branch and a hosting branch. (You may or may not name it gh_pages but I think that’d be wrong because that might imply that the github pages are project pages) and the just set the branch from which pages are being served to hosting in the settings. Then furthermore add an action that builds “into” the hosting branch on push. (But I’m too much of a noob yet to to the action).

I also want to stress that your example proved my point. The repo name != maintainer name => project type not user type => he needs to use the gh_pages branch.

Now I don’t have a project, I just want to use github for hosting and maintaining the site itself. I want something personal, so I opted for a user page which means repo name == maintainer name which implies that there’s no gh_pages branch.

4

I have set up many Hugo sites on GitHub, but only the “Project page” type and only generated with GitHub actions.

  1. Create the site.
  2. Add a “.github/workflows/gh-pages.yml” as mentioned in the docs.
  3. Add a “static/CNAME” file with the domain the site is going to use.
  4. Push the code to a GitHub repo.
  5. In the repo settings in the “Pages” section tell GitHub to serve pages from the root of the “gh-pages” branch (the action script will build and push that for you).
  6. Add a CNAME record pointing to “<USERNAME|ORGANIZATION>.github.io.” in the DNS.

Now the site will deploy on each new push to the “main” branch.

Quick and easy!

I do this while on a call with the customer. Then I help them set up a Forestry.io account and they can start add content to their new site before the call is over.

You can create the “gh-pages” branch with the generated content manually but that is a hassel. So mush easier to have GitHub action do it for you.

If you really want to generate the pages locally I would pick “docs” folder in “main” branch as the options in GitHub repo → Settings → “Pages”. Then you specify that Hugo should build the site in “docs” instead of “public”. I believe that should work but I have never tested it.

(The “User/Organisation” type pages seems only relevant if you plan to use https://<USERNAME|ORGANIZATION>.github.io/ as the actual address of the site.)

2 Likes
5

Only as an addition to the @frjo reply

For the local Hugo build

$> hugo --destination ./docs --theme hugo-theme --themesDir parentDir-of-hugo-theme --cleanDestinationDir --ignoreCache

This command builds the site to root/docs