diff --git a/content/codeberg-pages/migrating-from-pages-v2.md b/content/codeberg-pages/migrating-from-pages-v2.md
new file mode 100644
index 0000000..df92246
--- /dev/null
+++ b/content/codeberg-pages/migrating-from-pages-v2.md
@@ -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.
\ No newline at end of file