Documentation/content/codeberg-pages/migrating-from-pages-v2.md

---
eleventyNavigation:
  key: Migrating from Pages v2
  title: Migrating from Pages v2
  parent: CodebergPages
  order: 120
---
{% 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 %}

Since December 2025, Codeberg offers a new Pages service based on [git-pages](https://codeberg.org/git-pages/git-pages).
It improves performance and stability, and fixes various design issues from the current [Pages Server v2](https://codeberg.org/Codeberg/pages-server). Unfortunately, these fixed design issues require some migration and deprecation of features.

## Breaking changes and deprecations

Please be aware of the following changes and deprecated features.

* The recommended way to deploy websites is by directly uploading them to git-pages.
* Content is no longer fetched automatically. You need to use a method that informs git-pages about changes.
* `raw.codeberg.page` is no longer available. CORS headers are now directly set on your page and this workaround is no longer necessary.
* Direct access to repos and branches is no longer possible. You can no longer use the `/repository/@branch` access. `git-pages` restricts you to the website you explicitly deployed. Serving arbitrary resources from Codeberg was a common abuse vector and is going to be deprecated.

## The first push

Git-pages allows you to migrate without any downtime.
Your old v2 Pages deployment will continue working indefinitely.
Once you use one of the new deployment methods, your site will be served by the new server and not by the old one from then on.

Git-pages is engineered to be as compatible with existing v2 Codeberg Pages sites as possible.
Hopefully, you will only need to change the deployment method, and all your existing content will ‘just work’.

{% admonition "tip" %}

If you want to check that your content is being served with the new server, check the HTTP response headers.
If your content is being served by the old server, there will be a `Server` response header saying `pages-server`.
If it is being served by the new server, it will say `git-pages` only.

{% endadmonition %}

## Direct migration of Pages sites using a webhook

{% admonition "tip" %}

If you generate your website with a static site generator, you may be more interested in [the next section.](#switching-to-git-pages-forgejo-action)

{% endadmonition %}

If you create your website by uploading or pushing files to the `pages` branch directly and manually, you can also migrate to git-pages by setting up a webhook on your repository.
To do this:

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.

    If your repository *and* your branch are both called `pages`, you can omit the `repository-name` and just push to `https://username.codeberg.page/` directly.

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

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

You’re done!
Next time you push something new to the `pages` branch, the new git-pages server will serve your content instead of the old v2 Pages server.

## Switching to Git-pages Forgejo Action

If your `pages` branch is currently generated by pushing the output from a static site generator – especially if this push is triggered by Forgejo Actions – another easy way to migrate is to replace the step in your workflow that pushes your content with a new step that uses the officially supported git-pages Forgejo Action to deploy the site contents directly.

Information on how to do this is available on [the documentation page on using Forgejo Actions with git-pages.](/codeberg-pages/forgejo-actions/)