Migrating from Pages v2

Warning

Codeberg Pages is currently migrating from the legacy v2 codebase to the newer git-pages 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.

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.

Since December 2025, Codeberg offers a new Pages service based on git-pages. It improves performance and stability, and fixes various design issues from the current Pages Server v2. 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’.

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.

Direct migration of Pages sites using a webhook

Tip

If you generate your website with a static site generator, you may be more interested in the next section.

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.

Contributing

Hey there! 👋 Thank you for reading this article!

Is there something missing, or do you have an idea on how to improve the documentation? Do you want to write your own article?

You're invited to contribute to the Codeberg Documentation at its source code repository for example, by adding a pull request or joining in on the discussion in the issue tracker.

For an introduction on contributing to Codeberg Documentation, please have a look at the Contributor FAQ.