Table of contents

Introduction: An Automated Deployment Workflow

This guide details a process for establishing a fully automated Continuous Integration and Continuous Deployment (CI/CD) pipeline for a Hugo-based static website. The workflow utilizes a private GitLab repository for version control and Cloudflare Workers for the build and deployment process.

This configuration provides an efficient and scalable hosting solution. Once implemented, any commit pushed to the designated GitLab repository branch will automatically trigger a build and deployment to Cloudflare’s global network, eliminating the need for manual intervention.

Prerequisites

To implement this workflow, the following components are required:

  • A GitLab account with a configured private repository.
  • A Cloudflare account.
  • A local development environment with Hugo installed for content creation and testing.
  • Git installed for version control.

Step 1: Hugo Project and GitLab Repository

This guide presumes the existence of a functional Hugo project hosted in a private GitLab repository. The repository should contain all necessary project files, including content, themes, and Hugo configuration files.

Step 2: Local Development and Testing

  1. Start the Local Server:

    • Navigate to the root directory of your Hugo project in a terminal.

    • Run the following command:

      hugo server -D

    • The hugo server command starts a local web server with live-reloading enabled. The -D flag is crucial as it builds content marked as draft: true, allowing you to preview unpublished posts.

  2. Preview the Site:

    • Once the server is running, open a web browser and navigate to the address provided in the terminal, typically http://localhost:1313/.
    • Any changes saved to your project files will automatically trigger a rebuild, and the browser will refresh to display the updates.

  3. Stop the Server:

    • To stop the local server, return to the terminal and press Ctrl+C.

Step 3: Cloudflare Worker Configuration

This process uses Cloudflare Workers directly to provide granular control over the build and deployment environment.

  1. Instantiate a Cloudflare Worker:

    • Log in to the Cloudflare dashboard.
    • Navigate to Workers & Pages from the main menu on the left side (Inside Compute (Workers) folder).
    • Click Create button.
    • Select the Workers tab (selected by default) and click Get started on Import a repository.

    Image alt

  2. Integrate the GitLab Repository:

    • Select GitLab and follow the authorization prompts to grant Cloudflare access to your repositories.
    • Select the specific GitLab repository containing the Hugo project.

  3. Define Build Parameters:

    • Project name: Set to my-hugo-blog or your project name.

    • Build command: Specify the command to build the Hugo site.

      hugo --gc --minify

      The --gc flag enables garbage collection of unused assets, and --minify reduces the size of the output files for improved performance.

    • Deploy command: npx wrangler deploy. This will invoke Cloudflare wrangler to deploy the site to global network.

    Image alt

  4. Add wrangler.toml for Configuration: A wrangler.toml file is required in the repository’s root directory to instruct Cloudflare Workers on how to manage the project. This file designates the project as a static site.

    Create a file named wrangler.toml in the root of your project with the following content:

    name = "my-hugo-blog" # Must match the Cloudflare Worker name
compatibility_date = "2025-08-02" # Use the current date
assets = { directory = "./public/" }

    Commit and push this file to the GitLab repository:

    git add wrangler.toml
git commit -m "Add wrangler.toml configuration"
git push

Step 4: Initial Automated Deployment

The addition of the wrangler.toml file and the configured build settings will initiate an automatic deployment. The status of this process can be monitored from the Deployments tab within the Worker’s dashboard.

Upon successful deployment, the site will be accessible at the provided .workers.dev subdomain.

Step 5: Custom Domain Configuration

To associate a custom domain with the deployed site, follow these steps:

  • DNS Configuration:

  1. Go to your worker’s Settings tab.

  2. In Domains & Routes section, click Add.

  3. Follow the “Custom domain” option to configure the custom domain for your worker.

    Image alt

    If the domain is managed within Cloudflare, the required DNS records are typically created automatically. For domains managed by external registrars, you must update the nameserver records to point to Cloudflare.

Automated Deployment Workflow

The completed configuration establishes the following automated workflow, which relies on webhooks for communication:

  1. Local changes are made to the Hugo project.
  2. Changes are committed and pushed to the GitLab repository.
  3. Upon receiving the push, GitLab automatically sends a webhook notification to a unique Cloudflare URL. This event-driven approach means Cloudflare does not actively monitor the repository; it is notified of changes instantly.
  4. Triggered by the webhook, Cloudflare fetches the latest repository version, executes the specified hugo build command, and deploys the resulting static files to its global network.

Conclusion

This guide outlines a robust, automated CI/CD pipeline for deploying a Hugo static site. This serverless architecture provides a scalable, low-maintenance solution, enabling developers to focus on content creation while the deployment process is handled automatically.

References

For further information and official documentation, please consult the following resources: