Deploying a Hugo site on Gitea to Cloudflare Pages

At the time of writing, Cloudflare Pages only supports GitHub or GitLab. But you can use Gitea. In this post, I am going to show you how. It is very easy. This post will be very in-depth, it will cover steps that may be familiar to people who have used git or Hugo in the past, but it will also cover things you may not be aware of to get Cloudflare Pages working using your own Gitea.

What is assumed throughout:

  • You have git installed on your system and usable in VSCODE
  • You have hugo installed on your system and usable in VSCODE
  • You have Source Control enabled in VSCODE

Step 1 - Creating new Gitea repository ¶

Start by creating a repo on your Gitea instance, giving it the following:

  • Repository Name HugoGiteaGithubCFPages
  • .gitignore Hugo
  • Choose to keep the repository Private or not
  • Then scroll to the bottom and click Create Repository

Step 2 - Pulling your new Gitea repository locally for development ¶

In this post, I will be using Visual Studio Code for local development

  • Open a New Window in VSCode: File > New Window
  • Click Source Control on the left and then click Clone Repository

You should see a similar screen to this:

You may note that it shows Clone from Github. We shall not be doing that. In the text box above, Paste the URL for your repo from Gitea and then hit RETURN, mine is:

Your VSCODE should then look like this:

Step 3 - Creating a basic Hugo website ¶

Now, in VSCODE, click Terminal in the top menu, then New Terminal

We are following the Quick Start guide from the Hugo website, with some small edits: Hugo Quick Start

At the bottom of VSCODE a new Terminal window will appear, run the following command:

hugo new site . --force

This will create a basic Hugo website in the root of your HugoGiteaGithubCFPages, your directory will look like this once done:

Run the following command to add a basic theme:

git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke

Now we need a homepage. Create a new file called _index.md in the folder content with the following content:

---
title: "test site"
---

This is a test HugoGiteaGithubCFPages website!

Now your directory structure should look like this:

Now you can check it in your browser! Run the following in the Terminal

hugo server

You should then see something similar to the following:

Note the line

Web Server is available at http://localhost:62663/ (bind address 127.0.0.1)

This means, you can browse your website in your browser by going to the URL shown in your VSCODE terminal (it may differ slightly from mine)

If you’ve made it to this point, nice!. We can now move on to saving our changes to Gitea and then the next stage of pushing to a Private GitHub.com repo!

Step 4 - Saving your changes to Gitea ¶

You may have noticed a blue circle with a number on the left, meaning our changes have been noticed by VSCODE, my example shows the number 4 (yours may differ):

We can now save these changes to our Gitea instance by doing the following: Click Source Control on the left, and you’ll see this:

In the Message area write something and click Commit:

Now it will show another Message area, write something in and click Commit

Now you can click Sync Changes

Press OK on the pop-up:

Now you may need to enter your SSH key Passphrase, write it in and hit Return on your keyboard:

You have now completed syncing your changes with your Gitea instance.

A quick check-in Gitea shows the changes did save:

Step 5 - Making a Private GitHub.com repo and connecting it to Gitea ¶

  • Login to your GitHub account
  • Press the + top right
  • Click New Repository
  • Give it a Repository name such as HugoGiteaGithubCFPages (it can be anything you choose)
  • Make the repo Private
  • Click Create Repository

GitHub will then create a blank slate repository for you. Its URL is `https://github.com/jamieede123/HugoGiteaGithubCFPages`` in my case

You now need to create a “Personal Access Token” on GitHub, so you can auto-deploy your Gitea to GitHub.com

Read more here: Gitea Docs - Setting up Push mirror from Gitea to GitHub

  • When logged into GitHub, go to https://github.com/settings/profile
  • On the left-hand menu click Developer Settings
  • Now click Personal access tokens > Fine-grained tokens
  • Then click Generate new token
  • You may need to confirm your password
  • Now, you need to set the key:
    • Give the token a name
    • In Expiration use the calendar select to make the key the max age, which at the time of writing is 1 year
    • Click Only select repositories and then select the repository you created on GitHub, in this case, HugoGiteaGithubCFPages
    • Under Permissions select the following:
    1. Commit statuses = Access: Read and write
    2. Contents = Access: Read and write
    3. Issues = Access: Read and write
    4. Pull requests = Access: Read and write
  • Now you’re ready to click Generate token

You should then be shown something similar to below, copy the token to your clipboard:

  • Go to your Gitea instance & then open your repository, in my case: http://192.168.1.129:10037/jamieede/HugoGiteaGithubCFPages
  • Now, go to the Settings link for the repository
  • Next, scroll to Mirror Settings
  • In the Git Remote Repository URL text box enter your GitHub repo URL, in my case: https://github.com/jamieede123/HugoGiteaGithubCFPages
  • Expand the Authorization section just below this
  • Enter your GitHub username & the token
  • Ensure Sync when commits are pushed is ticked

Below is a screenshot example:

Now click Add Push Mirror You’ll then be greeted with:

The repository settings have been updated.

Scroll to Mirror Settings section and click Synchronize Now to sync your Gitea repo with your clean and empty GitHub repo.

You’ll then be greeted with:

Mirror synchronization is in progress. Check back in a minute.

Then once it syncs you’ll see a success message in the Last update section, as you can see, mine says:

Feb 22, 2023, 3:26:06 PM

Step 6 - Setting up Cloudflare Pages to pull from the GitHub repository ¶

Right, the next step is getting Cloudflare Pages to pull your GitHub repository for auto-deployment to Cloudflare Pages.

There is great documentation over at https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site

This will be a step-by-step based on steps covered above

Now that you’re logged in, choose your account & then select Pages from the menu, then click Create a project > Connect to Git

Then login with your GitHub.com account and select the repository we created HugoGiteaGithubCFPages

Your page should look similar to below:

Click Begin setup

Now:

  • Ensure you are happy with your Project name
  • Production branch being main is fine
  • In Framework preset find Hugo and select it
  • Expand Environment variables (advanced) and enter HUGO_VERSION = 0.101.0

That should be enough, you should have something similar to:

Click Save and deploy

Now, after a few seconds, the window should change and show the building and deployment process for your Hugo website!

Once it completes you should see something similar to:

Congratulations! It works!

Going to https://hugogiteagithubcfpages.pages.dev/ in the browser shows:

Step 7 - Testing Gitea updates to auto GitHub mirror to auto Cloudflare Pages deploy ¶

Ok, so, everything thus far works. But all this setup needs a quick test to see if it works as expected

We are going to make a Pull Request on Gitea and see if Gitea pushes the change to GitHub & Cloudflare Pages deploys automatically.

I am going to edit that _index.md we created earlier and give it the following content:

---
title: "test site"
---

## This is a test HugoGiteaGithubCFPages website!

I made the above a header instead & added this sentence.

Save this and then go to http://localhost:62663/ (in my case, check your URL!)

and you should see your changes live:

Now, in the Source Control area, we used last time, we are going to send the changes to our Gitea repo:

  • In Source Control Message enter my new change
  • Click Commit
  • In Message write the same my new change
  • Then click Sync Changes
  • Click OK
  • Enter SSH key password if required, hit RETURN

You will then see your change appear in Gitea:

It also matches your GitHub repository:

And, best of all, you’ll see Cloudflare Pages auto-deploy your change!

Browsing to the given new Cloudflare Pages URL will show the new changes: https://hugogiteagithubcfpages.pages.dev/

Yes, we’re done, it works! You can now customize your site, enable a custom domain, anything you want.

For help to set up Custom domains and other features you can utilize with Cloudflare Pages, read more using the following helpful resources:

Cloudflare Pages docs Cloudflare Pages docs - How to section

Plus much more within it, plus the Cloudflare Community is a great resource

For Hugo development start here:

https://gohugo.io/getting-started/quick-start/

Thanks for reading, reach out on Twitter if you have any issues or comments @jamierede

×
Page views: 0