Codeberg Pages

Last updated on 2026-10-19 | Edit this page

Estimated time: 40 minutes

Overview

Questions

  • What is Codeberg Pages?
  • How can I use Codeberg Pages to collaborate and share my work?

Objectives

  • create a pages branch and push a website to it
  • publish the branch as a website with Codeberg Pages
  • with a partner, experiment with collaborating on a Codeberg Pages website
  • apply the workflow between local and remote repositories to collaborate on a website

Codeberg Pages

Codeberg Pages is a service for publishing a website directly from a Git repository on Codeberg. You put the files of your website (HTML, CSS, images, …) into a branch called pages, and Codeberg Pages makes them available at https://yourname.codeberg.page/repository-name/.

Why Codeberg Pages is awesome!

Codeberg Pages allows you to version control your website. This is useful for a lot of different reasons. It allows you to keep a record of what changes you have made. It allows people to reference your website at a particular point in time and (if you make your source open) to see what it was like at that particular point in time. This is very useful for academic citations. Most people have had the experience of following up a reference to a website and either getting a 404 error or seeing something completely different. Although using versions on your site doesn’t guarantee this won’t happen, it does make it easier to manage old versions of your site.

Codeberg Pages also means that you can collaborate on a website with a lot of people without everyone having to communicate endlessly back and forwards about what changes need to be made, or have been made already. You can create ‘issues’ (things that need discussing or fixing), list things to do in the future, and allow other people visiting your website to quickly suggest, and help implement changes through pull requests.

Callout

What about Markdown?

Codeberg Pages publishes your files exactly as they are: it does not convert Markdown into HTML. An index.md file would be shown as plain text, so in this episode we write a small HTML page instead.

If you prefer to write your website in Markdown, you can use a static site generator (for example Hugo, Jekyll or Quarto) to turn your Markdown files into HTML, and let a CI service such as Woodpecker CI or Forgejo Actions build and push the result to the pages branch automatically. This is exactly how the website of this lesson is made.

Create a pages branch

Up to now, all our commits went into the main branch. A branch is a separate line of development in the same repository. Codeberg Pages only looks at a branch named pages, so let’s create it in our local hello-world repository:

BASH 

$ git switch -c pages

OUTPUT 

Switched to a new branch 'pages'

Here, switch tells Git to change the current branch, the -c tells Git you want to create a new branch, and pages is what it will be called. The new branch starts with all the commits that are in main at the moment.

Now create a file called index.html with your text editor:

BASH 

$ nano index.html

and enter a minimal web page, for example:

HTML 

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Hello, world!</title>
  </head>
  <body>
    <h1>Hello, world!</h1>
    <p>This is my first website on Codeberg Pages.</p>
  </body>
</html>

Save the file, then add and commit it as usual:

BASH 

$ git add index.html
$ git commit -m "Add index.html"

Enable Codeberg Pages

Before we push the new branch, we need to tell Codeberg Pages that our repository has a website. This is done with a webhook: every time something is pushed to the pages branch, Codeberg sends a short message to the Pages service, which then publishes the new version of the site.

  1. Go to your hello-world repository on Codeberg and click “Settings”. Make sure the repository is public: Codeberg Pages only publishes public repositories.
  2. Click “Webhooks” in the menu on the left side, then “Add webhook” and select “Forgejo”.
  3. Enter https://yourname.codeberg.page/hello-world/ as the “Target URL”, with yourname replaced by your Codeberg username.
  4. Enter pages in the “Branch filter” field.
  5. Click “Add webhook” at the bottom of the page.
Caution

Don’t test the webhook

The webhook page offers a “Test delivery” button. Don’t use it: the test is expected to fail and does not tell you anything about whether your site works. Push to the pages branch instead.

Push and view your site

Now push the new branch to Codeberg. As this is the first push of the pages branch, we use -u again to set its upstream:

BASH 

$ git push -u origin pages

If we now visit https://some-librarian.codeberg.page/hello-world/ (with some-librarian replaced by your username), we should see the web page we just created. Usually it’s available within a few seconds. If it isn’t, check the webhook in the repository settings: under “Recent deliveries” you can see whether Codeberg was able to notify the Pages service.

Challenge

Challenge: Contributing to a page owned by someone else (slightly easier way)

To practice using Git, Codeberg and HTML we can contribute to a Codeberg Pages site. Pair up in groups of two (or more if needed) and do the exercises below together.

  1. Go to https://codeberg.org/some-librarian/hello-world, where “some-librarian” is the username of your exercise partner.

  2. Click on “Fork” in the upper right part of the screen to create a copy of the repository on your account. As you already have your own hello-world repository, you will need to use a different name for it, such as hello-world-1. Once you have a fork of your partner’s repository, you can edit the files in your own fork directly.

  3. In your fork, use the branch selector above the file list to switch to the pages branch. Click the “index.html” file, then click the edit pencil icon (“Edit file”).

  4. Now is a good chance to try some HTML. Add a paragraph (<p>...</p>), a list (<ul><li>...</li></ul>) or a link (<a href="...">...</a>). The MDN introduction to HTML has many more examples.

  5. Once you are ready to commit, enter a short commit message, select “Create a new branch for this commit and start a pull request” and press “Propose file change” to avoid committing directly to the pages branch.

  6. On the next screen, check that the pull request goes from the new branch in your fork into the pages branch of your partner’s repository (Codeberg may suggest main as the target, so change it if necessary). Review the changes, add an explanation and click “Create pull request”.

  7. Your partner should now see a pull request under the “Pull requests” tab of their repository and can accept the changes there by clicking the “Merge” button. Try this. A moment later, the change will be visible on your partner’s website.

This whole process of making a fork and a pull request might seem a bit cumbersome. Try to think of why it was needed? And why it’s called “pull request”?

We made a fork and a pull request because we did not have permission to edit (or commit) the repository directly. A fork is a copy of the repository that we can edit. By making a pull request we ask the owner of the repository if they would like to accept (pull in) the changes from our fork (our copy) into their version. The owner can then review the changes and choose to accept or reject them.

You can open pull requests on any public repository you find on Codeberg. If you are a group of people who plan to collaborate closely, on the other hand, it’s more practical to grant everyone access to commit directly instead (in the repository settings under “Collaborators”).

Callout

Branching and merging

Branches get their name because you can create a new one (say, “patch”) that splits off from an existing one like “main”, allowing different sets of changes to be made in parallel. Later on, Git can take the changes from “patch” and merge (copy) them into the “main” branch. In the last challenge, Codeberg did all this for us in the background.

The label ‘main’ points to commit c5; arrows point from c5 to c3 to c1 to c0. The label ‘patch’ points to commit c4; arrows point from c4 to c2 to c1. A dotted arrow points from c5 to c4.
Challenge

Optional challenge: Contributing to a page owned by someone else (slightly more complicated way)

Instead of making edits on the Codeberg website you can ‘clone’ the fork to your local machine and work there. There are several reasons why you might want to do this:

  • you need to move content from one file to another;
  • you need to make changes to several files at once;
  • you find it easier to work in your desktop software than in a web form.

Pair up in groups of two (or more if needed) and follow the steps below together. If you have already tackled the previous challenge, you can use the fork you created there and skip to step 3.

  1. Go to https://codeberg.org/some-librarian/hello-world, where “some-librarian” is the username of your exercise partner.

  2. Click on “Fork” in the upper right part of the screen to create a copy of that repository on your account. As you already have your own hello-world repository, you will need to use a different name for it, such as hello-world-1.

  3. In your own fork, find the clone address above the list of files and copy it. Just like when you connected your local repository to Codeberg, make sure “SSH” is selected, so the link starts with git@codeberg.org:.

  4. Go back to your shell terminal window. If you’re in your own Git repository, use the cd command to come out of it:

    BASH 

    # To check where you are:
$ pwd
# To go up one directory:
$ cd ..

    Change the following command to use the link you just copied and run it:

    BASH 

    $ git clone git@codeberg.org:<your_codeberg_username>/hello-world-1.git

    The clone command creates a directory on your computer containing the current state of the repository and its full version history.

  5. Enter the directory that Git just created and switch to the pages branch:

    BASH 

    $ cd hello-world-1
$ git switch pages

  6. Create a new branch to hold the changes you’re about to make:

    BASH 

    $ git switch -c my-patch-1

  7. Open up the index.html and start editing it.

  8. After saving the file, add it, commit it with a short message describing the change:

    BASH 

    $ git add index.html
$ git commit -m "Add a list of favourite books"

  9. Push your new branch up to your fork on Codeberg:

    BASH 

    $ git push origin my-patch-1

  10. Git will show you a message from Codeberg containing a link for starting a new pull request:

    OUTPUT 

    remote:
remote: Create a new pull request for 'my-patch-1':
remote:   https://codeberg.org/<your_codeberg_username>/hello-world-1/compare/main...my-patch-1
remote:

    You can visit that link in your browser, or go to your partner’s repository, open the “Pull requests” tab and click “New pull request”.

  11. Make sure that the pull request goes into the pages branch of your partner’s repository and comes from the my-patch-1 branch of your fork. The next screen lets you add a description to explain your changes to the repository owner, and change the title to make it clearer (this is especially useful if you make a single pull request for multiple commits). When you’re ready, click on the “Create pull request” button.

  12. Your partner should now see a pull request under the “Pull requests” tab and can accept the changes there by clicking “Merge”. Try this.

Challenge

Optional challenge: Adding a second page

A website usually consists of more than one page. Try adding another HTML page to your repository. You could do this on the command line or directly on Codeberg. The steps below are for working directly on Codeberg:

  1. Make sure you are looking at the pages branch of your repository. To add a new file directly on Codeberg, click “Add file” and then “New file”.

  2. Name it test.html, add some HTML and click “Commit changes”.

  3. Try opening https://some-librarian.codeberg.page/hello-world/test.html (replace “some-librarian” with your username).

  4. Link the new page from your index.html with <a href="test.html">My test page</a>.

Key Points
  • Codeberg Pages publishes the pages branch of a public repository as a website that is version controlled and accessible for collaboration
  • Codeberg Pages serves files as they are; Markdown needs to be converted to HTML first, for example by a static site generator
  • Collaborating on a Codeberg Pages website uses the same Git/Codeberg workflow you learned for collaborating via a Codeberg repository