Using git-pages on Codeberg¶

A while ago has Codeberg announced their completion of their git-pages rollout.¹
This means that you are now able to publish your site on Codeberg using their git-pages² instance, which brings some benefits, but also drawbacks to consider

I'll use this oportunity to now make an updated version of my original Blog Post for Codeberg Pages, covering how you can publish your site using ProperDocs³ and Forgejo Actions.

Why git-pages?¶

Codeberg has provided their own service called pages-server⁴ for a long time now and while it did work and has some cool features, has it entered a maintenance-mode state, with git-pages being the recommended alternative to use.

The primary reason for using git-pages, is that it actually deploys the created site to then serve.
The pages-server did not do such a thing. Instead was it pulling the site content directly from the configured repository to serve.
While this allowed a often time quicker updating if site changes, did it put a lot of stress on the backend, leading to nummerous downtimes.

Through git-pages is the content static and simply needs to be served without any pulling from a repository being required, reducing operations and significantly boosting performance and stability, at the cost of changes requiring a re-deployment to take effect.

Note

While pages-server is in maintenance mode and git-pages is the recommended alternative, does Codeberg have no plans for removing pages-server, nor shut it down. Sites served through pages-server remain functional and the old method remains supported.

Smaller Drawbacks¶

git-pages, while having great feature-parity with pages-server, has some smaller drawbacks to consider:

The raw.codeberg.page sub-domain can not be used on git-pages repos to obtain a Site's raw content. Instead are sites deployed with proper CORS headers, allowing you to now use the content directly from the site domain used.
This means, that if you used raw.codeberg.org to pull raw files (i.e. JS files) from your site, you now need to replace it with your site's domain and may need to update the path too.
The @branch feature to display content of a specific repository branch does not work anymore on git-pages sites. This functionality was not included in git-pages for security reasons and constant abuse in the past.
This also means, that you can no longer use this for features like PR previews, unless you keep using your old pages-server setup.

Deploying to git-pages¶

This section will cover how you can configure a Forgejo Workflow to deploy your page build through ProperDocs.
While this is the recommended aproach, can you also deploy your site by pushing it to a repository or branch and setup a Webhook targeting your site's domain. This aproach may be easier, as it doesn't require you to configure a TXT DNS entry for your custom domain, but comes at the cost of an extra branch/repository needed.

A quick note about custom domains¶

If you want to deploy your site for a custom domain (i.e. example.com) are some DNS changes required.
Namely, you need to add the following DNS entry to your custom domain:

Type	Name	Value
`TXT`	`_git-pages-forge-allowlist`	URL to your repository deploying the site.

As an example, the following TXT entry would be needed, if you want to deploy your site from codeberg.org/Knut/ExampleSite to example.com:

_git-pages-forge-allowlist.example.com. TXT "https://codeberg.org/Knut/ExampleSite"

For codeberg.page sub-pages is the only requirement, that the {user}.codeberg.page/{repository} matches the User/Organisation and Repository name that it is being deployed from.
Example: If deploying from codeberg.org/Knut/ExampleSite, the site option needs to be https://knut.codeberg.page/ExampleSite.

Only exception is for the {user}.codeberg.page domain itself. If you want to deploy to it directly, is the Repository required to be named pages.

Should you want to deploy to a codeberg.page domain from a Repository without a matching name, will you need to create a Personal Access Token with Read and Write permission for the Repository scope.

The Workflow File¶

The following Workflow can be used to deploy to git-pages on Codeberg:

deploy_site.yml

name: Deploy Site

on:
  push: # (1)

jobs:
  publish:
    run-on: codeberg-tiny
    steps:
      - name: "Checkout Repository"
        uses: https://code.forgejo.org/actions/checkout@v6
        with:
          fetch-depth: 0 # (2)
      - name: "Setup Python"
        uses: https://code.forgejo.org/actions/setup-python@v6
        with:
          python-version: 3.x
      - name: "Install dependencies"
        run: "pip install -r requirements" # (3)
      - name: "Build Site"
        run: "properdocs build"
      - name: "Deploy Site"
        uses: https://code.forgejo.org/actions/git-pages@v2
        with:
          site: https://example.com # (4)
          token: ${{ secrets.FORGEJO_TOKEN }} # (5)
          source: site/ # (6)

I highly recommend adding branches and paths filters to only trigger this workflow on specific branches and for specific file changes.
Example:
```
on:
  push:
    branches:
      - main
    paths:
      - ".forgejo/workflows/deploy_site.yml"
      - "docs/**"
      - "properdocs.yml"
      - "requirements.txt"
```
Should you also publish releases on your repository (or push tags) do I recommend to also add tags-ignore: ["**"] to ignore any tags being created, as those counts as pushes too.
Avoids issues with plugins that require proper git history to work right (i.e. git-revision-date-localized-plugin)
Change this to whatever command(s) you need. It's recommended to keep your dependencies in a requirements.txt for easier updating and maintenance.
Set this to either the custom domain you use (i.e. https://example.com) or the {user}.codeberg.page domain you deploy this to, based on the following rules:
- If the repository is named pages can/should the domain be https://{user}.codeberg.page where {user} is the Account owning the Repository.
- If the repository is not named pages should the domain be https://{user}.codeberg.page/{repository} where {user} is the Account owning the Repository and {repository} is the Repository name itself.
This doesn't need to be changed, unless you want to deploy from a Repository to a {user}.codeberg.page/{repository} domain, where {repository} is different (i.e. You deploy to knut.codeberg.page/hello from codeberg.org/knut/world).
This should be the name of the site_dir used by ProperDocs which is site by default.
Note that the action defaults to _site/ so you need to change this unless you configured ProperDocs to build to _site.

Once pushed will this trigger a Workflow that checks out your repository, sets up python, installs the dependencies, builds the site and deploys it.
If everything goes well will your site be deployed and be available at the configured domain.

Footnotes

Comments

Comment system powered by Mastodon.
Leave a comment using Mastodon or another Fediverse-compatible account.

Last update: 24. April 2026 ()