Upgrading HugoBlox

Keeping your site updated ensures you have the latest features, security patches, and performance improvements.

We know that maintaining a website can be a chore—especially for busy researchers and data scientists. That’s why we’ve built a Zero-Touch Automated Upgrader to handle the heavy lifting for you.

Tip

New to HugoBlox? You likely already have the automated updater installed! Check your repository for a file at .github/workflows/upgrade.yml.

🤖 The Automated Way (Recommended)

The most robust way to upgrade is to let our GitHub Action do it for you. It runs weekly, checks for updates, applies migrations automatically, and creates a safe Pull Request for you to review.

How it works

1. Weekly Check: Every Monday, the bot checks if a new stable version of HugoBlox is available.
2. Smart Migration: It runs the HugoBlox CLI to update go.mod, patch config files, and apply any required breaking-change migrations.
3. Safe Proposal: Instead of breaking your live site, it opens a Pull Request (PR) titled “⬆️ Upgrade HugoBlox Modules”.
4. Review: Go to your GitHub repository and open the Pull requests tab. Click the upgrade PR. If your repo has deploy previews enabled (for example, GitHub Pages or Netlify), click the Deploy Preview link in the PR checks/comments to preview the updated site before merging.
5. Merge: If the preview looks good, scroll to the bottom of the PR page. Click the arrow next to the merge button, choose Squash and merge, and then click Confirm squash and merge. (We recommend squash merging to keep your repo history clean and make rollbacks easier.)

(The updater creates a PR for you)

(Review the changes and merge)

Setting it up

If your repository doesn’t have the updater yet, you can add it in 2 minutes.

Prerequisite: Enable Pull Request Permissions

For the automated upgrader to create Pull Requests, you need to enable the following permissions in your GitHub repository (these permissions control what GITHUB_TOKEN can do in workflows):

1. Go to your GitHub repository, then open Settings.
2. In the left sidebar, click Actions, then click General.
3. Scroll to the bottom until you see Workflow permissions.
4. Select Read and write permissions.
5. Enable Allow GitHub Actions to create and approve pull requests.
6. Click Save.

If you skip this step, the workflow may run but fail to open a PR.

Install the Workflow

1. Create the workflow file

   In your repository, create a new file at this path:

   • Directory.github

     • Directoryworkflows

       • upgrade.yml

2. Paste the configuration

   Copy the code from templates/academic-cv/.github/workflows/upgrade.yml into upgrade.yml.

3. Commit and relax

   Commit the file to your default branch (usually main). That’s it! You’ll now receive updates automatically.

Manually triggering an update

Don’t want to wait for Monday? You can trigger the updater anytime:

1. Go to the Actions tab in your GitHub repository.
2. Select Upgrade HugoBlox from the sidebar.
3. Click the Run workflow dropdown.
4. (Optional) Choose Stable (default) or Canary (bleeding edge).
5. Click the green Run workflow button.

---

💻 The CLI Way (Local)

If you prefer working in your local terminal, you can run the same upgrade logic manually.

1. Open your project

   cd my-hugo-blox-site

2. Run the upgrade command

   # Interactive (recommended locally)
   npx -y hugoblox@latest upgrade

   The CLI will check for updates and verify Hugo compatibility. If you use --yes/--ci, it will also apply any required migrations automatically.

   # Non-interactive (good for scripts/CI)
   npx -y hugoblox@latest upgrade --yes

3. Preview changes

   pnpm dev

Advanced Options

• --canary: Upgrade to the latest development commit (main). (Bleeding edge.)
• --force: Upgrade even if your local Hugo version is older than required.
• --apply-migrations: Apply migrations after upgrading (useful if you want to apply them during an interactive run).
• --skip-migrations: Skip migrations (even in --yes/--ci) if you want to review changes first.

---

❓ Common Questions

Why are there breaking changes?

We know breaking changes are annoying. However, HugoBlox is built on top of Hugo, the world’s fastest static site generator. Hugo is actively developed and frequently releases major improvements (like the recent shift to Tailwind CSS v4) which sometimes require changes to how sites are built.

Our automated upgrader is designed to bridge this gap. It contains “fixer” scripts that automatically rewrite your configuration to match the new requirements, letting you focus on your research and content, not on syntax changes.

I’m on a “Canary” build. Will the auto-updater downgrade me?

No. We have built a smart safety check into the updater. If you are using a development version (Canary) that is newer than the latest stable release, the updater will skip the update to prevent downgrading your site. You will only be prompted to update when a newer stable version is released that supersedes your dev build.

The workflow ran, but no PR was created. Why?

This is almost always a permissions/config issue in GitHub:

1. Confirm Settings > Actions > General > Workflow permissions is set to Read and write permissions.
2. Confirm Allow GitHub Actions to create and approve pull requests is enabled.
3. Re-run the workflow and check the workflow logs for permission errors such as “Resource not accessible by integration”.
4. If your repo has strict branch protection rules, ensure the workflow is allowed to push a branch and open a PR against your default branch.

I need help!

If an upgrade fails or your site looks wrong in the preview:

1. Check the PR Body: The automated PR often contains notes about what changed.
2. Ask AI: Paste the error into the HugoBlox AI Assistant.
3. Community Support: Join our Discord community where other researchers and the core team can help.