kgess-mirror/codeberg-Documentation
1
0
Fork 0
mirror of https://codeberg.org/Codeberg/Documentation.git synced 2026-01-16 23:10:42 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

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

Browse source
This commit is contained in:
fnetX 2025-12-02 21:24:17 +01:00 • committed by Catherine
parent 515e166a44
commit 7d3093430d
1 changed files with 39 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
content/codeberg-pages/migrating-from-pages-v2.md Normal file
View file

@ -0,0 +1,39 @@
---
eleventyNavigation:
key: Migrating from Pages v2
title: Migrating from Pages v2
parent: CodebergPages
order: 99
---
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. Fallback via a repository called "pages" is available.
* Content is no longer fetched automatically. You need to create a webhook 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 gone. 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. Currently, traffic to *.codeberg.page is proxied through git-pages, and as long as it was not instructed to serve your domain, it will forward the traffic to the Pages Server v2.
As soon as you do the first deployment to the new git-pages, it will take care of your website and will stop forwarding traffic. This change applies per user.codeberg.page or custom domain. If you are currently serving a different site at user.codeberg.page/someproject, it will also vanish once you deploy something to user.codeberg.page for the first time.
## Migration: Pushing pages
This is one of two deployment options for pages. You can now conveniently push the output of static site generators to git-pages without the previous workaround that required you to push changes back to Git repositories on Codeberg.org.
This assumes you already have a workflow that builds your static site, e.g. in a CI workflow.
Replace the step that pushes the output back to a Git repository after the run with one of the options, sorted from most to least convenient:
* If you are using Forgejo Actions, make use of the [git-pages action](https://codeberg.org/git-pages/action) which will take care of pushing the output to git-pages.
* Use the [`git-pages-cli`}(https://codeberg.org/git-pages/git-pages-cli) to push from your static site generator.
* Use curl to upload the site: `curl https://{domain}/ -X PUT -H "Authorization: Pages {password}" -H "Content-Type: application/..." --data-binary @{archive}`. Replace the content type with one of
* `application/x-tar+zstd` for .tar.zstd. Using [Zstandard](https://facebook.github.io/zstd/) level 0 to 3 is recommended, especially for large sites: it is a very efficient compression algorithm that will likely reduce the total energy used to publish the site.
* `application/x-tar+gzip`: for .tar.gz.
* `application/zip`: for a .zip archive.