Documentation/content/codeberg-pages/index.md

---
eleventyNavigation:
  key: CodebergPages
  title: Codeberg Pages
  icon: server
  order: 60
---

{% admonition "Warning" %}

Codeberg Pages is currently migrating from the legacy v2 codebase to the newer [git-pages](https://git-pages.org/) codebase.

Currently, websites that use custom domains can only be deployed using the old method, but we are working to fix this.
Such websites will keep working indefinitely.
You will be able to seamlessly migrate to the new version of Pages once it is supported.
Take note of some minor [changes and deprecations](/codeberg-pages/migrating-from-pages-v2/#breaking-changes-and-deprecations).

Websites hosted under the `codeberg.page` domain can already use the new git-pages method.

The new documentation is work in progress, and we appreciate your feedback. Please let us know in case you find yourself confused.

{% endadmonition %}

Codeberg Pages allows you to easily publish static websites with a human-friendly address (`{username}.codeberg.page`) or your custom domain on Codeberg.
You can publish an website for your user or organization, as well as websites for each repository.

Codeberg Pages are served using a deployment of [git-pages](https://git-pages.org/), which itself is [developed on Codeberg](https://codeberg.org/git-pages/git-pages).
It is free/libre open source software.
Git-pages works with any Forgejo host out there, as well as many other Git forges.
If you are running your own forge, you can also run it yourself and help with the development.

See also:

- [codeberg.page](https://codeberg.page)
- [Troubleshooting (Codeberg Documentation)](troubleshooting)

{% sectionNav collections %}

## Getting started with a `codeberg.page` URL

There are two ways to get started with Codeberg Pages on git-pages:

1. Using a [webhook](/advanced/using-webhooks/) on your repository
2. Using [Forgejo Actions](/codeberg-pages/forgejo-actions/) to deploy the output of a static site generator

This page documents the first method. See the [separate page on using Forgejo Actions](/codeberg-pages/forgejo-actions/) for information on the second method.

### User/organization websites

1. Create a repository called `pages` under your own username or under the organization you want to create a website for

    The website will be published from a branch also called `pages`. You can also set this as the default branch, if you prefer.

2. Go to **Settings** at the top right of your repository page.

3. Click **Webhooks** in the sidebar on the left.

4. Click the **Add webhook** button in the top right corner of the webhook settings page.

    Select **Forgejo** from the drop-down list of webhook types.

5. Enter `https://username.codeberg.page/` as the **Target URL**, replacing the `username` with your Codeberg username or organization name. This is the URL your website will be available from.

6. Set the **Branch filter** to `pages`.

7. Click the **Add webhook** button at the bottom of the settings page.

8. Push or upload your content to the `pages` branch, and it will automatically be published to `https://username.codeberg.page/`.

### Repository websites

1. Go to **Settings** at the top right of your repository page.

2. Click **Webhooks** in the sidebar on the left.

3. Click the **Add webhook** button in the top right corner of the webhook settings page.

    Select **Forgejo** from the drop-down list of webhook types.

4. Enter `https://username.codeberg.page/repository-name/` as the **Target URL**, replacing the `username` with your Codeberg username or organization name, and `repository-name` with the name of your repository. This is the URL your website will be available from.

5. Set the **Branch filter** to `pages`.

6. Click the **Add webhook** button at the bottom of the settings page.

7. Push or upload your content to a branch called `pages` on your repository, and it will automatically be published to `https://username.codeberg.page/repository-name/`.

## Getting started with a custom domain

{% admonition "warning" %}

You can only use the ‘legacy’ v2 Pages deployment method at the moment if you want to serve your site with a custom domain.

Websites deployed this way will keep working indefinitely.
You will be able to seamlessly migrate to the new version of Pages once it is supported.

{% endadmonition %}

There are two steps to getting started with a custom domain: configuration on Codeberg’s side, and configuration on the side of your DNS.

To set up your website for publication on a custom domain on the Codeberg side, simply upload your content to a branch of a repository called `pages`. You then also need to create a plain text file called `.domains` listing the domains your website should be available at.

You then need to set up DNS records to point to Codeberg. Instructions on how to do this are available on the [documentation page about using custom domains](/codeberg-pages/using-custom-domain/).

## Having problems?

See our [troubleshooting page](/codeberg-pages/troubleshooting).

## Advanced usage: custom 404 pages, redirects, and rewrites

For sites hosted with Codeberg Pages, you can customize the look of the 404 page when someone tries to access a page that doesn’t exist, and you can make URLs redirect to other URLs or serve the same content as at some other URL.

See the [advanced usage](/codeberg-pages/advanced-usage/) documentation to learn how to do these things.

## Do you have questions, feedback, or have you found a bug?

Support for Codeberg Pages is available at the [Pages Server repository](https://codeberg.org/Codeberg/pages-server);
feel free to head there to provide some feedback, suggestions, bug reports or even patches.
If you need general community support or have questions, [Codeberg/Community](https://codeberg.org/Codeberg/Community)
is a better place to ask, as more people will be watching there to help you out!
We really appreciate your contribution.