Troubleshooting

My web browser displays a security warning when I try to access my Codeberg Pages

If your user name or repository name contains a dot, your Codeberg Pages URL (https://user.name.codeberg.page or https://repo.sitory.username.codeberg.page) contains a sub-sub-domain which does not work with Let's Encrypt wildcard certificates. Use the alternative URL https://pages.codeberg.org/user.name/ as a workaround or rename you repository (e.g. replace . by _).

My content is not updated

The Codeberg Pages v2 server caches files under a certain size (currently 1 MiB). Please wait a few minutes until the cache has been invalidated. This is done to improve performance, reduce cost and server load, and save energy.

Cloudflare and Codeberg Pages

It is important that when you use Cloudflare to manage your Domain's DNS records, that every DNS record used for Codeberg Pages needs to be set to DNS only (Have a gray cloud). This ensures that Codeberg pages can properly handle everything necessary for your site such as SSL-Certificate and redirects from other (sub-)domains.

Troubleshooting post-git-pages errors

Given that Codeberg has moved to git-pages entirely, some behaviors changed. Some things broke. Including some undocumented behaviors website authors depended on. This needs troubleshooting. Luckily, git-pages allows troubleshooting.

Say, we add this (broken) redirect rule to simulate old pages server redirection to .html pages:

/*/ /:splat.html 301

After committing it and opening a page like https://example.org/hello, we are redirected to a 404 page. Something must be broken in redirects. However, we don’t know that for sure. Need to check.

There are two ways to find out what’s broken in the website:

# Plain web request
curl https://example.org/.git-pages/manifest.json
# Or a dedicated tool from git-pages
git-pages-cli --debug-manifest https://example.org

In either case, you get huge JSONs with meta-information about the website. The structure is roughly:

{
  "repoUrl": "https://codeberg.org/.../pages.git",
  "branch": "pages",
  "commit": "abcdef...",
  "contents": {
    "": {
      "type": "Directory"
    },
    ".domains": {
      // ...
    },
    ".gitignore": {
      // ...
    },
    "assets": {
      "type": "Directory"
    },
    "assets/...png": {
      "type": "ExternalFile",
      "originalSize": "...",
      "compressedSize": "...",
      "data": "...",
      "transform": "Identity",
      "contentType": "image/png",
      "gitHash": "..."
    },
    "index.html": {
      "type": "ExternalFile",
      "originalSize": "...",
      "compressedSize": "...",
      "data": "...",
      "transform": "Zstd",
      "contentType": "text/html; charset=utf-8",
      "gitHash": "..."
    }
    // ...
  },
  "originalSize": "...",
  "compressedSize": "...",
  "storedSize": "...",
  "redirects": [
    {
      "from": "/foo",
      "to": "/bar",
      "status": 301,
      "force": false
    }
    // ...
  ],
  "headers": [],
  "basicAuth": [],
  "problems": [
    {
      "path": "_redirects",
      "cause": "rule #1 \"/*/ /:splat.html 301\": splat * must be its own final segment of the path"
    }
  ]
}

And here’s the problem, under the "problems" key: the redirect is malformed! In the end, this is one of the changes and deprecations that happened in migration. But lamenting that is a story for another time. Problem diagnosed through the useful git-pages manifest! Use it to diagnose errors from now on!