How to deploy a Quarto website on Codeberg Pages

quarto
git
codeberg
ci
woodpecker
Published

August 12, 2025

These instructions are relatively detailed and broken down into small steps, but you should be familiar with the basic functions and principles of Git.

About Quarto

Quarto is an open-source system for scientific and technical publications. Code can be executed (Python, R, etc.) and Quarto has the ability to publish Markdowntexts in many formats (HTML, PDF, MS Word, ePub, etc.) simultaneously using Pandoc. This website was created and built with Quarto.

Background

A website created with Quarto can be easily hosted and displayed on a web server. However, it can also be automatically stored on various publishing services. With continuous integration (CI), it is possible to automate the build process, e.g., in a Git repository. This site was previously hosted on GitHub; instructions for this can be found in the Quarto documentation. In my search for a GitHub alternative outside the US, I chose Codeberg. Like many other Git providers, Codeberg offers Codeberg Pages, a way to host static websites from a repository. Since there is no documentation for Codeberg from Quarto itself, I would like to describe the procedure for Quarto publishing with CI, which I implemented based on the Codeberg documentation and an existing implementation (many thanks to Georg Rüppel).

Implementation

Preparation

In addition to an account with Codeberg, you must activate CI, which is implemented via Woodpecker, as described here. To do this, there must be a LICENSE file in the repository (see the Codeberg documentation for details). Once the account has been activated, the repository can be activated in Woodpecker as described here.

If you want to use your own domain, this must be set up accordingly. Codeberg provides instructions for this: https://docs.codeberg.org/codeberg-pages/using-custom-domain/

Create workflow

A .woodpecker folder must then be created in the repository itself, in which a pages.yml file is created. This is what it looks like for me:

when:
  - branch: main
    event: push

steps:
  render:
    image: ghcr.io/quarto-dev/quarto
    commands:
      - quarto render
      - if [ -f “.domains” ]; then cp “.domains” _site/; fi

  deploy:
    image: codeberg.org/xfix/plugin-codeberg-pages-deploy:1
    settings:
      folder: _site
      ssh_key:
        from_secret: ssh_key

This workflow is executed when a push event occurs on the main branch, as we have added a filter using the when section:

when:
  - branch: main
    event: push

Two steps are then defined: render and deploy. The steps are executed in the order in which they were defined.

  1. render
    Quarto provides an official image on GitHub. This is integrated using the image command: image: ghcr.io/quarto-dev/quarto This is followed by two execution commands:

    • quarto render causes Quarto to render the files from the repository as a website.

    • Optional, must be available to use your own domain: This is followed by a Bash command that copies the .domains file to the output folder of the rendered website (_site): if [ -f “.domains” ]; then cp “.domains” _site/; fi.

  2. deploy
    A plugin is used to move the generated page (the _site folder) to the pages branch. The configuration of the plugin, including sample code, is explained here: https://codeberg.org/xfix/plugin-codeberg-pages-deploy. The folder parameter must be adjusted in the code so that the correct folder is published: folder: _site.

Execution

The pipeline is now automatically processed with each push to the repository. You can view the status on the Woodpecker page under Repositories: https://ci.codeberg.org. Error messages that are useful for debugging may also be displayed there.

Sources

You can also take a look at my own repository: https://codeberg.org/tem/personal-website

Back to top