How to Fix Codeberg Pages Deployment Error

In this tutorial, you'll learn about How to Fix Codeberg Pages Deployment Error. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

Codeberg Pages shows 404 Not Found after committing a .forgejo/workflows/pages.yml file or the build pipeline fails with Error: failed to deploy pages artifact.

The Problem

Error: Failed to deploy pages artifact
The workflow run completed but the pages deployment failed.

Step-by-Step Fix

Step 1: Create a correct Pages workflow

# .forgejo/workflows/pages.yml
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build site
        run: |
          mkdir -p public
          echo "Hello, Codeberg Pages!" > public/index.html
      - uses: actions/upload-pages-artifact@v3
        with:
          path: public
  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    steps:
      - uses: actions/deploy-pages@v4

Step 2: Enable Pages in the repo settings

Go to Settings > Pages and set the branch to pages.

Step 3: Configure custom domain

Create a file called public/.domains:

blog.example.com

Add a CNAME record in your DNS: blog.example.com CNAME yourusername.codeberg.page.

Step 4: Check the deployment status

curl -I https://yourusername.codeberg.page/repo/

Expected: HTTP/2 200

Prevention Tips

• Keep the public/ directory in .gitignore and let CI generate it
• Use actions/configure-pages@v4 for framework detection
• Test builds locally with the same Hugo/SSG version Codeberg uses

Common Mistakes with pages

1. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
2. Using return to exit a function early instead of wrapping a pure value in the monad
3. Mixing let bindings with <- bindings in do notation, producing type errors

These mistakes appear frequently in real-world CODEBERG code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ