How to Set Up a Website on Codeberg Pages

Updated

You can host a static website on Codeberg Pages by pushing files to a public repository at Codeberg. The site becomes available at https://USERNAME.codeberg.page (or https://USERNAME.codeberg.page/REPOSITORY). You have two deployment paths: a webhook for hand-written static files, or a Forgejo Actions workflow if you use a static site generator like Jekyll or Hugo.

Prerequisites

  • A Codeberg account (the username or organization name becomes part of your URL).
  • A public repository. Pages are served from public repos.
  • Static content only — HTML, CSS, fonts, images, and similar files. There is no server-side runtime.

Option A: Deploy plain static files via webhook

Use this if you write your HTML/CSS by hand and just want to push changes.

1. Set up your repository

Pick one of two layouts:

  • Main subdomain: create a public repository named pages with a branch called pages. This serves at the main subdomain.
  • Project subdomain: create a branch called pages inside any public repository:
git switch --orphan pages
git rm --cached -r .

2. Set up deployment

  1. In your repository, go to Settings → Webhooks and click Add webhook.
  2. Select Forgejo from the webhook type dropdown.
  3. Set the Target URL to your site's URL:
    • No custom domain: https://USERNAME.codeberg.page/REPOSITORY (replace USERNAME with your user or organization name and REPOSITORY with the repo name). If the repository is called pages, omit the repository part.
    • With a custom domain: configure the domain first (see below), then use that URL.
  4. Set the Branch filter to pages.
  5. Click Add webhook.

3. Upload your files

Push your static content to the pages branch. It will be accessible at https://USERNAME.codeberg.page[/REPOSITORY].

Option B: Deploy with CI (static site generators)

If you use a static site generator such as Jekyll, Hugo, or a similar tool, you can integrate deployment into a Forgejo Actions workflow that builds your site. Codeberg's documentation covers the workflow setup — this is the path to choose when your source files need a build step before they become static output.

Custom domain configuration

DNS records

Add one of the following on your domain:

  • CNAME codeberg.page.
  • For apex domains where CNAME doesn't work: ALIAS codeberg.page.
  • If ALIAS isn't supported, add the TXT record described below and use both:
    • A 217.197.84.141
    • AAAA 2a0a:4580:103f:c0de::2

Authorization TXT record

Add a TXT record authorizing the Codeberg Pages server to deploy your repository. Place it on the subdomain _git-pages-repository with the Git HTTPS clone URL of your repository as the value:

TXT https://codeberg.org/user/repo.git

Which option should you pick?

Situation Use
Hand-written HTML/CSS, no build step Webhook (Option A)
Jekyll, Hugo, or another generator Forgejo Actions (Option B)
Want the site at the main subdomain Repo named pages with a pages branch
Want the site under a project path pages branch in any public repo
Custom domain Add DNS records plus the _git-pages-repository TXT record

Common sticking points

  • Repository must be public. Private repos won't serve Pages.
  • Branch name matters. The webhook branch filter and the serving branch are both pages; pushing to another branch won't deploy.
  • Apex domains and CNAME. CNAME records don't work at the apex, so use ALIAS, or the TXT + A/AAAA combination.
  • Forgetting the authorization TXT record. Custom domains need the _git-pages-repository TXT record pointing at your repo's HTTPS clone URL, or the server won't deploy to it.
  • Repo named pages. When your repository is called pages, the repository segment is dropped from the URL.