codeberg.page

Codeberg Pages is a static website hosting service built into Codeberg. You put your site's files into a Git repository on Codeberg, and Codeberg serves them as a live website. It's designed for open source project homepages, developer blogs, and web experiments, and the service describes itself as quick, easy, free, and fast. It only serves static content — HTML, CSS, fonts, images, and similar files — so there's no server-side code execution.

How the hosting model works

Your website lives in a Git repository, and Codeberg Pages maps that repository (or a specific branch of it) to a URL. Two things determine where your site appears:

• A repository named pages with a branch named pages makes the site available at the main subdomain.
• A pages branch inside any public repository publishes that repository's site at a URL that includes the repository name.

The resulting address follows this pattern:

https://USERNAME.codeberg.page/REPOSITORY

USERNAME is your user or organization name, and REPOSITORY is the repository name. If the repository itself is called pages, the repository segment is omitted.

Two ways to deploy

Codeberg Pages supports both automated and manual publishing.

With CI (static site generators)

If you build your site with a generator such as Jekyll, Hugo, or a similar tool, you can integrate deployment into a Forgejo Actions workflow that builds the site. Codeberg's documentation covers the workflow setup.

Without CI (plain static files)

If you're serving hand-made static files, you configure a webhook on your repository to deploy changes. The documented steps are:

1. Set up your repository. Either create a public repository named pages with a branch called pages, or create a pages branch in an existing public repository:

   git switch --orphan pages
   git rm --cached -r .
   

2. Set up deployment. In your repository's Settings, go to Webhooks and click Add webhook. Choose Forgejo as the webhook type. Set the Target URL to your site's URL (for example, https://USERNAME.codeberg.page/REPOSITORY, or the custom domain if you have one). Set the Branch filter to pages, then click Add webhook.

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

Using a custom domain

You can point your own domain at Codeberg Pages. The configuration has two parts: DNS records and an authorization record.

DNS records — add one of the following on your domain:

If ALIAS isn't supported, the documented fallback is to add the TXT record described below and use the A + AAAA records together.

Authorization record — add a TXT record to the subdomain _git-pages-repository containing the Git HTTPS clone URL of your repository:

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

This authorizes the Codeberg Pages server to deploy your repository to the server.

What to check before you start

• Static only. Codeberg Pages serves files; it doesn't run backend code. If your project needs a database or server logic, this isn't the right host.
• Public repositories. The documented setup uses public repositories, so treat everything you push as publicly visible.
• Branch name matters. The pages branch is what gets deployed in the webhook setup, and the branch filter must match it.
• Custom domains need both DNS and TXT records. Missing the _git-pages-repository TXT record will block deployment to your domain even if DNS resolves correctly.

If your goal is a project homepage, a static blog, or a small web experiment that fits in a Git repo, Codeberg Pages covers it without a separate hosting account.

Your Codeberg Pages site is served at https://USERNAME.codeberg.page/REPOSITORY, where USERNAME is your Codeberg user or organization name and REPOSITORY is the name of the repository holding the site. The one exception: if the repository is named pages, the repository segment is dropped and the site lives at https://USERNAME.codeberg.page/. If you attach a custom domain, visitors use that domain instead.

The default URL structure

Codeberg Pages maps a repository to a subdomain of codeberg.page:

Two details matter here:

• USERNAME is the owner, not the pusher. If the repository belongs to an organization, the organization name appears in the URL, not your personal username.
• The repository name is case-sensitive in the URL path. Match the exact repository name as it appears on Codeberg.

Why the pages repository is special

A repository literally named pages is treated as the account's main site, so it occupies the bare subdomain https://USERNAME.codeberg.page/ with no path segment. This is the closest equivalent to a "user site" — one per account, at the root of your subdomain.

Any other repository name becomes a path under that subdomain. So USERNAME.codeberg.page/REPOSITORY is the general case, and USERNAME.codeberg.page/ is the reserved case for the repository named pages.

What you need for the URL to resolve

The URL only serves content once three things are in place:

1. A public repository — private repositories are not served.
2. A branch named pages — this is the branch Codeberg Pages deploys from, regardless of your default branch.
3. Deployment configured — either a Forgejo Actions workflow (for static site generators like Jekyll or Hugo) or a webhook pointing at your site URL with the branch filter set to pages.

If you use the webhook route, the Target URL you enter is the same URL your visitors will use — https://USERNAME.codeberg.page/REPOSITORY (or without the repository segment when the repo is named pages). Setting it correctly is what tells the deploy server where the site belongs.

Switching to a custom domain

Once a custom domain is configured, that domain becomes the address visitors use; the codeberg.page URL is no longer the public entry point. Configuration involves:

• A DNS record: CNAME codeberg.page. — or ALIAS codeberg.page. for apex domains where CNAME does not work.
• If ALIAS is unsupported, a TXT record plus A 217.197.84.141 and AAAA 2a0a:4580:103f:c0de::2.
• A TXT record on _git-pages-repository containing the Git HTTPS clone URL of your repository (https://codeberg.org/user/repo.git), which authorizes the Pages server to deploy it.

Plan your repository name with this in mind: renaming a repository later changes its default URL, so pick the name you want before you start publishing.

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?

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.

To point your own domain at a Codeberg Pages site, you add DNS records at your domain registrar and then authorize Codeberg to serve your repository on that domain. The exact records depend on whether you use a subdomain (where CNAME works) or an apex/root domain (where you need ALIAS, or A + AAAA plus a TXT authorization record). You also need a TXT record under _git-pages-repository so the Codeberg Pages server is allowed to deploy your repository.

Before you start

• Your site must already be deployed on Codeberg Pages, reachable at https://USERNAME.codeberg.page/REPOSITORY (or https://USERNAME.codeberg.page if the repository is named pages).
• You need access to your domain's DNS settings.
• DNS changes can take time to propagate, so verify with a DNS lookup tool if the domain doesn't resolve immediately.

Step 1: Add the DNS record for your domain

The record type depends on the kind of domain you're pointing.

For subdomains (CNAME)

Add a CNAME record:

CNAME codeberg.page.

For apex domains (ALIAS)

If your DNS provider supports ALIAS, use it for the apex domain:

ALIAS codeberg.page.

For apex domains without ALIAS support

If ALIAS isn't supported, add the TXT record described in Step 2, then use A and AAAA records:

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

Step 2: Authorize Codeberg Pages to deploy your repository

Add a TXT record on the subdomain _git-pages-repository. Its value is the Git HTTPS clone URL of your repository:

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

Replace user and repo with your actual Codeberg username (or organization) and repository name. This record tells the Codeberg Pages server that it's allowed to deploy your repository to the server.

Step 3: Confirm the setup

Once the records are in place, your site should be served on your custom domain. If you set up deployment via a webhook (the non-CI path), make sure the webhook's Target URL points to your custom domain rather than the default USERNAME.codeberg.page address.

Common issues

• Apex domain won't resolve with CNAME. CNAME records generally don't work at the apex, which is why ALIAS or A + AAAA are used instead.
• Missing authorization record. Without the TXT record under _git-pages-repository, the Codeberg Pages server won't deploy your repository to the server.
• Wrong repository URL in the TXT record. The value must be the Git HTTPS clone URL (https://codeberg.org/user/repo.git), not the Pages URL.
• Webhook still pointing at the default subdomain. If you use a webhook for deployment, update its Target URL to your custom domain after configuring DNS.

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

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.