Should I deploy Codeberg Pages with CI or without CI?

Updated

Use CI if your site is generated by a tool such as Jekyll or Hugo and you want the build to run automatically after each push. Use the webhook method if you already have plain, hand-made static files (HTML, CSS, images, fonts) and just want them served. Both paths publish to Codeberg Pages; the difference is whether Codeberg builds your site for you or you upload the finished output yourself.

The two deployment paths

With CI (Forgejo Actions) Without CI (webhook)
Best for Static site generators: Jekyll, Hugo, or similar Plain hand-made static files
What you push Source files; the workflow builds the site The finished files themselves
Build step Runs in the Forgejo Actions workflow None — you generate files locally
Setup effort Requires a workflow configuration Requires a repository webhook
When it fits You want deployment integrated into your build You want the simplest possible setup

Choose CI when you use a static site generator

If your site comes from a generator like Jekyll or Hugo, Codeberg's documentation describes integrating deployment into the Forgejo Actions workflow that builds your site. In practice this means you commit your source and configuration, and the workflow produces the output that gets published — you don't commit a pre-built site by hand.

This is the better fit when:

  • Your content lives in Markdown, templates, or other source formats rather than final HTML.
  • You want the site rebuilt every time you push, without running the generator locally first.
  • You're comfortable maintaining a workflow file alongside your content.

The trade-off is that you take on the workflow configuration. If the build fails, the published site won't update, so you need to watch the action results.

Choose the webhook method when you have plain static files

If you "just want to serve plain old hand-made static files," the documented route is to configure a webhook on your repository to deploy changes to Codeberg Pages. There is no build step — whatever you push is what gets served.

Step 1: Set up your repository

You have two options:

  • Create a public repository named pages with a branch called pages. This makes the site available at the main subdomain.
  • Or create a pages branch in any public repository:
git switch --orphan pages
git rm --cached -r .

Step 2: Set up deployment

  1. In your repository's Settings, go to Webhooks and click Add webhook.
  2. Select Forgejo from the drop-down list of webhook types.
  3. Set the Target URL to your site's URL. Without a custom domain, that's https://USERNAME.codeberg.page/REPOSITORY — replace USERNAME with your user or organization name and REPOSITORY with the repository name. If the repository is called pages, omit the repository part.
  4. Set the Branch filter to pages.
  5. Click Add webhook.

If you're using a custom domain, configure it first (see below) and use that URL as the target.

Step 3: Upload your files

Push your static content — HTML, styles, fonts, images, anything else. It becomes accessible at https://USERNAME.codeberg.page[/REPOSITORY].

Custom domain configuration

Add a DNS record 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 A + AAAA instead:

  • A 217.197.84.141
  • AAAA 2a0a:4580:103f:c0de::2

Then add a TXT record authorizing the Codeberg Pages server to deploy your repository. Put it on the subdomain _git-pages-repository with the Git HTTPS clone URL of your repository:

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

How to decide

  • Site generated by Jekyll, Hugo, or similar → CI. You keep source in the repo and let the workflow build it.
  • Site is already final HTML/CSS/assets → webhook. Fewer moving parts; you push what you want served.
  • Not sure yet? Start with the webhook method to confirm your files serve correctly at https://USERNAME.codeberg.page[/REPOSITORY], then move to CI if you later adopt a generator.

One thing to check before either path: the repository must be public, and the branch must be named pages.