dallasgroot/Documentation
1
0
Fork 0
mirror of https://codeberg.org/Codeberg/Documentation.git synced 2026-06-16 05:13:54 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update Codeberg Pages docs for git-pages custom domain support

Browse source
This commit is contained in:
Daphne Preston-Kendal 2026-05-28 18:39:02 +02:00
parent e0fe2eaa66
commit e42be0ea82
3 changed files with 104 additions and 346 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
content/codeberg-pages/index.md
View file

@ -8,14 +8,12 @@ eleventyNavigation:
{% admonition "Warning" %}
Codeberg Pages is currently migrating from the legacy v2 codebase to the newer [git-pages](https://git-pages.org/) codebase.
Codeberg Pages has recently migrated 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.
If you have not yet [migrated your own site to the new server,](/codeberg-pages/migrating-from-pages-v2/) we encourage you to do so.
We do not currently have any concrete plans to disable Pages Server v2.
The new documentation is work in progress, and we appreciate your feedback. Please let us know in case you find yourself confused.

127
content/codeberg-pages/pushing-output.md
View file

@ -1,127 +0,0 @@
---
eleventyNavigation:
key: PushingOutput
title: Pushing output from SSGs into Codeberg Pages
parent: CodebergPages
author: Fayçal Alami Hassani - https://codeberg.org/ka2in
order: 110
---
{% 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.
**This page documents the method used for legacy v2 Pages sites.**
You should be able to adapt the directions for git-pages (assuming you are not using a custom domain) using, for example, the [instructions on using Forgejo Actions with git-pages](/codeberg-pages/forgejo-actions/).
The new documentation is work in progress.
We hope to update this page with information on how to use the new server directly with static side generators soon.
In the meanwhile, we appreciate your feedback.
Please let us know in case you find yourself confused.
{% endadmonition %}
If you are using a static site generator (SSG) and are satisfied with the result of your project on your local development
environment, you can push the files to your Codeberg Pages repository.
## Manual pushing
To begin with, we will have two separate repositories, both locally and on Codeberg:
- A main repository for the source files, i.e. where the source files related to your main project will be located.
We will refer to this repository as the `source` repository.
- A second repository for Codeberg pages that we will call the `pages` repository.
This repository will only contain the files available in the `html` folder located under docs/build/html.
{% admonition "warning" %}
The `pages` repository **must** be public, as Codeberg Pages will directly fetch the files from the repository,
just like an ordinary user would.
{% endadmonition %}
{% admonition "info" %}
For the purpose of this guide, we have chosen to use two separate folders/repositories.
However, you may want to have a different setup that involves creating a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
instead of having folders and repositories in separate locations. With a submodule, your configuration may look like so:
```bash
├── sources --> This is a git repo
│ ├── build
│ │ └── html
│ │ └── pages --> This is a separate git repo
│ └── content
```
{% endadmonition %}
To copy the content of the `html` folder to your new `pages` folder, run the command:
```bash
(.venv) $ cp -R docs/build/html/ pages
```
We will now initialize an empty repository inside the pages folder. To do this, type the command:
```bash
git init
```
To check the status of your project’s files, type the command:
```bash
git status
```
To add all the files that are available in your directory to Git, run the command:
```bash
git add -A
```
Now we will commit:
```bash
git commit -m "Example commit message"
```
Repeat these steps in your `source` folder, then push your local commits to the remote repository with the command:
```bash
git push origin HEAD:your-remote-branch-name
```
{% admonition "info" "Note" %}
Replace `your-remote-branch-name` with the name of your remote branch. It is recommended to initially push your commits
to a branch other than the default branch. Once you have made sure everything went smoothly, you can then make a pull
request to merge it into the default branch. To learn more about pull requests, read the article
[Pull requests and Git flow](https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/).
{% endadmonition %}
You should now be able to access your content by visiting https://{username}.codeberg.page.
You can find more information in the [Codeberg Pages](/codeberg-pages/) section.
## Using a CI
Both the [Woodpecker CI](/ci/#using-codeberg's-instance-of-woodpecker-ci) and the [hosted Forgejo Actions](/ci/actions/)
can be used to automate the build and deployment of your static website.
For the Woodpecker CI, you can see the [existing example workflows in the `Codeberg-CI/examples` repo](https://codeberg.org/Codeberg-CI/examples),
which provides examples for Jekyll, Hugo, Zola and many other popular SSG.
Currently, we do not have any examples for the Forgejo Actions yet, but individual SSG tools might
have details in their own documentation.
Note that if you use Forgejo Actions to publish the website, you should make sure that `.domains`
file will be preserved in the root directory of the **output** branch or repository.

315
content/codeberg-pages/using-custom-domain.md
View file

@ -5,6 +5,18 @@ eleventyNavigation:
parent: CodebergPages
order: 10
---
{% admonition "Warning" %}
Codeberg Pages has recently migrated 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).
If you have not yet [migrated your own site to the new server,](/codeberg-pages/migrating-from-pages-v2/) we encourage you to do so.
We do not currently have any concrete plans to disable Pages Server v2.
The new documentation is work in progress, and we appreciate your feedback. Please let us know in case you find yourself confused.
{% endadmonition %}
{% admonition "Warning" %}
@ -35,70 +47,6 @@ In this case you must add `A` / `AAAA` / `TXT` records for all domains instead o
{% endadmonition %}
For custom domains, two things are required:
- a `.domains` file in the repository and branch where your files reside which you want to publish via Codeberg Pages.
The file should contain a list of all external domains that shall be usable to access that repository,
according to the following rules:
- One domain per line, you can leave lines empty and comment out lines with `#`.
- The first domain is the main domain, all other domains in the file will be redirected to the first one.
- a [DNS record](https://en.wikipedia.org/wiki/Domain_Name_System#Address_resolution_mechanism) pointing to one of the
following targets, depending on where your static files reside:
<br />
{% admonition "question" "Why do I need all of these DNS records?" %}
To understand how the Pages server serves content, you need to know that a user browsing your custom domain just sends
"Hey, I want to see `yourdomain.com`" to the server.
But the server might not know that it is responsible for `yourdomain.com` and it cannot just serve all domains in the world.
So to find out if the server is responsible for `yourdomain.com` it will check the DNS entries of `yourdomain.com`.
If it returns something with `codeberg.page` (according to the domain schemes mentioned below) then it knows which
repository to check for the `.domains` file and your content.
{% endadmonition %}
## Setting the DNS record
There are several ways DNS records for your website can be setup in order to tell the Pages server your repository location.
For all of the options it is important that the Pages server knows where to look for the `.domains` file and your content.
Depending on from where you want to serve your files, there is a naming scheme for the domain:
<table class="table">
<thead>
<th>Domain Scheme</th>
<th>Pages URL</th>
</thead>
<tbody>
<tr>
<td>
<code>username.codeberg.page</code>
</td>
<td>
https://username.codeberg.page<br />which will serve <code>codeberg.org/username/pages</code>
</td>
</tr>
<tr>
<td>
<code>reponame.username.codeberg.page</code>
</td>
<td>
https://username.codeberg.page/reponame<br />which will serve <code>codeberg.org/username/reponame</code>
</td>
</tr>
<tr>
<td>
<code>branchname.reponame.username.codeberg.page</code>
</td>
<td>
https://username.codeberg.page/reponame/@branchname/<br />
which will serve <code>codeberg.org/username/reponame/src/branch/branchname</code>
</td>
</tr>
</tbody>
<table>
{% admonition "warning" "Repository names with dots are not supported" %}
Repository names containing dots (`.`) are **not supported** for custom domains.
@ -131,7 +79,7 @@ Therefore, in this guide, you may need to replace references to just your domain
{% endadmonition %}
### Option 1: CNAME record
### Step 1: CNAME, ALIAS, or A/AAAA record
The easiest and recommended way is to just setup a CNAME record for your domain, pointing to the mentioned above locations.
In the end, it should look like this:
@ -146,12 +94,12 @@ In the end, it should look like this:
<tr>
<td>yourdomain.com</td>
<td>CNAME</td>
<td>reponame.username.codeberg.page</td>
<td>codeberg.page.</td>
</tr>
<tr>
<td>www.yourdomain.com</td>
<td>CNAME</td>
<td>reponame.username.codeberg.page</td>
<td>codeberg.page.</td>
</tr>
</tbody>
</table>
@ -167,18 +115,8 @@ If you need email or others services, you have to use one of the remaining optio
{% endadmonition %}
### Option 2: ALIAS record
If you cannot use a CNAME record to configure the target you can use this method, which needs two entries instead of one.
- First you need to specify which server should be serving your website. Similar to CNAME you can use an `ALIAS record`.
The [difference](https://www.ecosia.org/search?q=cname%20vs%20alias%20record) between an CNAME record is,
that the DNS server directly responds with the ip address and not the `codeberg.page` domain.
Therefore you need to add a second entry, so that the pages server knows what to serve under this domain.
- Second, you need to setup a `TXT record` which contains the information from the `CNAME entry` which is your repository
location as mentioned above. For example `[[branch.]repo.]user.codeberg.page`.
In the end it should look like this:
If you have an apex domain you will not be able to use a CNAME record.
In this case, many DNS providers support an ALIAS record which will work instead.
<table class="table">
<thead>
@ -188,29 +126,25 @@ In the end it should look like this:
</thead>
<tbody>
<tr>
<td>yourdomain.com</td><td>ALIAS</td><td>codeberg.page</td>
<td>yourdomain.com</td>
<td>ALIAS</td>
<td>codeberg.page.</td>
</tr>
<tr>
<td>yourdomain.com</td><td>TXT</td><td>reponame.username.codeberg.page</td>
</tr>
<tr>
<td>www.yourdomain.com</td><td>CNAME</td><td>reponame.username.codeberg.page</td>
<td>www.yourdomain.com</td>
<td>ALIAS</td>
<td>codeberg.page.</td>
</tr>
</tbody>
</table>
### Option 3: A/AAAA record
<br />
If your service provider does not support `ALIAS records` you can also use `A records` and `AAAA records` instead.
If you cannot use a CNAME nor an ALIAS record,
you will need to set up the A and AAAA records to point to Codeberg’s IP addresses directly.
- First you need to specify which server should be serving your website. You can do this by setting an `A record` for IPv4
and an `AAAA record` for IPv6 which contains the ip address of the Codeberg Pages server. The servers' ip addresses are:
- `A record` which contains the IPv4 value `217.197.84.141`
- `AAAA record` which contains the IPv6 value `2a0a:4580:103f:c0de::2`
- Second, you need to setup a `TXT record` which contains the information of your repository
location as mentioned above. For example `[[branch.]repo.]user.codeberg.page`.
In the end, it should look like this:
It is possible these IP addresses will change in future,
so keep an eye on Codeberg updates to check.
<table class="table">
<thead>
@ -229,138 +163,91 @@ In the end, it should look like this:
<td>AAAA</td>
<td>2a0a:4580:103f:c0de::2</td>
</tr>
</tbody>
</table>
### Step 2: Configure Git-pages authorization
{% admonition "question" "Why do I need all these extra DNS records?" %}
When someone tries to deploy a website to your domain,
Codeberg Pages needs to know which repository is responsible for the content,
and that the content actually comes from that repository.
When the webhook or Forgejo Action are triggered,
the server receives a token letting it know that the repository’s policies allowed the deploy.
The DNS records in turn ensure that the domain owner authorizes that repository to be deployed to that domain.
{% endadmonition %}
**If you deploy from a webhook,**
set a TXT record on the `_git-pages-repository` subdomain of your domain with the HTTPS Git clone URL for your repository.
<table class="table">
<thead>
<th>Domain</th>
<th>Type</th>
<th>Data</th>
</thead>
<tbody>
<tr>
<td>yourdomain.com</td>
<td>_git-pages-repository.yourdomain.com</td>
<td>TXT</td>
<td>reponame.username.codeberg.page</td>
<td>https://codeberg.org/username/repository.git</td>
</tr>
<tr>
<td>_git-pages-repository.www.yourdomain.com</td>
<td>TXT</td>
<td>https://codeberg.org/username/repository.git</td>
</tr>
</tbody>
</table>
## Examples
**If you deploy from Forgejo Actions,**
set a TXT record on the `_git-pages-forge-allowlist` subdomain of your domain with the HTTPS Git clone URL for your repository.
The following sub-sections include a few examples of the different alternatives, assuming the following:
<table class="table">
<thead>
<th>Domain</th>
<th>Type</th>
<th>Data</th>
</thead>
<tbody>
<tr>
<td>_git-pages-forge-allowlist.yourdomain.com</td>
<td>TXT</td>
<td>https://codeberg.org/username/repository.git</td>
</tr>
<tr>
<td>_git-pages-forge-allowlist.www.yourdomain.com</td>
<td>TXT</td>
<td>https://codeberg.org/username/repository.git</td>
</tr>
</tbody>
</table>
- we can add/modify DNS records in domain `example.com`.
- Our Codeberg username is `frida`, and we want to publish pages for:
- `frida/pages`, with a _Personal_ static site inside branch `pages`;
- `frida/colormix`, with a _Project_ site (again, inside branch `pages`).
### Step 3: Set your webhook or Forgejo Actions deploy target
All considerations regarding a _Personal_ site also apply to an _Organization_ site, so these two cases will be
addressed together.
**If you deploy from a webhook,**
the webhook **Target URL** should be set to the domain you want to deploy your website to.
### Personal (or Organization) site, subdomain
**If you deploy from Forgejo Actions,**
the `site` parameter to the Git-pages action should be set to the URL of your custom domain.
In this case, we want our _Personal_ pages available at the URL `https://myself.example.com`.
### Deploying to versions of your domain both with and without `www.`
The `.domains` file contains the following:
If you would like to serve your website at versions with and without a `www.` prefix,
you should choose one of them to be the ‘canonical’ URL,
add a [`_redirects` file](/codeberg-pages/advanced-usage/) to your site redirecting from one version to the other,
and deploy your website to both domains. (I.e. set up two separate webhooks, or use two separate deploy actions.)
```text
myself.example.com
For example, to redirect people from www.yourdomain.com to yourdomain.com,
use this `_redirects` file:
```
//www.yourdomain.com/* https://yourdomain.com/:splat 302!
```
For the DNS configuration:
- if the domain is not the apex of the zone and does not have other services such as email,
you should always use a CNAME record:
- name `myself.example.com`, type `CNAME`, data `frida.codeberg.page`
- otherwise, if ALIAS can be used, two DNS records will be needed:
- name `myself.example.com`, type `ALIAS`, data `codeberg.page`
- name `myself.example.com`, type `TXT`, data `frida.codeberg.page`
- otherwise, A/AAAA records must be used, together with one TXT record:
- name `myself.example.com`, type `A`, data `217.197.84.141`
- name `myself.example.com`, type `AAAA`, data `2a0a:4580:103f:c0de::2`
- name `myself.example.com`, type `TXT`, data `frida.codeberg.page`
### Personal/Organization site, apex domain
In this case, we want our _Personal_/_Organization_ pages available at the URL `https://example.com`.
We also want the URL `https://www.example.com` to redirect to the apex domain.
The `.domains` file contains the following:
```text
example.com
www.example.com
```
_You may also put the `www` subdomain on the first line if you wish to use it as the canonical URL_
_and redirect the apex domain instead._
For the DNS configuration, CNAME records CANNOT be used for the apex domain, so:
- if ALIAS can be used, three DNS records will be needed:
- name `example.com`, type `ALIAS`, data `codeberg.page`
- name `example.com`, type `TXT`, data `frida.codeberg.page`
- name `www.example.com`, type `CNAME`, data `frida.codeberg.page`
_Note that ALIAS records are not real DNS records and are typically incompatible with DNSSEC signed zones._
- otherwise, A/AAAA records must be used, together with a TXT record:
- name `example.com`, type `A`, data `217.197.84.141`
- name `example.com`, type `AAAA`, data `2a0a:4580:103f:c0de::2`
- name `example.com`, type `TXT`, data `frida.codeberg.page`
- name `www.example.com`, type `CNAME`, data `frida.codeberg.page`
### Project site, subdomain
In this case, we want our _Project_ pages available at the URL `https://colormix-app.example.com`.
The `.domains` file contains the following:
```text
colormix-app.example.com
```
For the DNS configuration:
- if the domain is not the apex of the zone and does not have other services such as email,
you should always use a CNAME record:
- name `colormix-app.example.com`, type `CNAME`, data `colormix.frida.codeberg.page`
- otherwise, if ALIAS can be used, two DNS records will be needed:
- name `colormix-app.example.com`, type `ALIAS`, data `codeberg.page`
- name `colormix-app.example.com`, type `TXT`, data `colormix.frida.codeberg.page`
- otherwise, A/AAAA records must be used, together with one TXT record:
- name `colormix-app.example.com`, type `A`, data `217.197.84.141`
- name `colormix-app.example.com`, type `AAAA`, data `2a0a:4580:103f:c0de::2`
- name `colormix-app.example.com`, type `TXT`, data `colormix.frida.codeberg.page`
### Project site, apex domain
In this case, we want our _Project_ pages available at the URL `https://example.com`.
{% admonition "info" "Note" %}
This would be incompatible with using the apex `example.com` for other purposes, e.g. for the _Personal_/_Organization_
example discussed before.
{% endadmonition %}
The `.domains` file contains the following:
```text
example.com
www.example.com
```
_You may also put the `www` subdomain on the first line if you wish to use it as the canonical URL_
_and redirect the apex domain instead._
For the DNS configuration, CNAME records CANNOT be used for the apex domain, so:
- if ALIAS can be used, three DNS records will be needed:
- name `example.com`, type `ALIAS`, data `codeberg.page`
- name `example.com`, type `TXT`, data `colormix.frida.codeberg.page`
- name `www.example.com`, type `CNAME`, data `colormix.frida.codeberg.page`
_Note that ALIAS records are not real DNS records and are typically incompatible with DNSSEC signed zones._
- otherwise, A/AAAA records must be used, together with one TXT record:
- name `example.com`, type `A`, data `217.197.84.141`
- name `example.com`, type `AAAA`, data `2a0a:4580:103f:c0de::2`
- name `example.com`, type `TXT`, data `colormix.frida.codeberg.page`
- name `www.example.com`, type `CNAME`, data `colormix.frida.codeberg.page`
For the redirect to work,
you should be sure that the code (here `302!`) includes an `!` at the end.
Otherwise, the redirect will only work on pages which are otherwise not found.