mirror of
https://codeberg.org/Codeberg/Documentation.git
synced 2026-08-15 14:53:29 -07:00
38dd33db6c
Hi! This updates Pages docs with more details on git-pages quirks and troubleshooting. Adapted from https://aartaka.me/codeberg-pages.html#git-pages Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/854 Reviewed-by: Catherine <whitequark@whitequark.org>
90 lines
5 KiB
Markdown
90 lines
5 KiB
Markdown
---
|
||
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.
|
||
|
||
Take note of some minor [changes and deprecations](/codeberg-pages/migrating-from-pages-v2/#breaking-changes-and-deprecations).
|
||
|
||
The new documentation is work in progress, and we appreciate your feedback. Please let us know in case you find yourself confused.
|
||
|
||
{% endadmonition %}
|
||
|
||
{% admonition "info" "Notice" %}
|
||
|
||
Custom domains are now supported by the new git-pages server! Please refer to [the updated custom domain setup guide](/codeberg-pages/using-custom-domain/) for details on how to properly replace your old DNS records before proceeding.
|
||
|
||
{% 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.
|
||
- There no longer are automatic redirections from `path` to `path.html`, add a [redirect rule](/codeberg-pages/advanced-usage/#redirects) for each of the pages you need to redirect.
|
||
- Splat redirects only work for simple `/old-path/* /new-path/:splat` patterns of moved posts, no way to e.g. replace file extension with `/* /:splat.html`.
|
||
|
||
## 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/)
|