Skip to content
CodeFloe

Configuration

Building your site

Section titled “Building your site”

There is no build step on the hosting side: CodeFloe serves the files it is given, exactly as they are.

That leaves two ways to publish, and which you want depends on whether your site needs generating.

Publish from a branch

Section titled “Publish from a branch”

If your site is already plain HTML, put it on a branch and select that branch in the Pages settings. CodeFloe publishes its contents whenever it changes.

Build and publish from Actions

Section titled “Build and publish from Actions”

If your site is generated (Astro, Hugo, Jekyll, MkDocs, a bundler) build it in Forgejo Actions and push the result to your Pages branch. Keep the source on one branch and the built site on another, so generated files never land in the branch you work in.

A working example lives at codefloe/pages-example.

# .forgejo/workflows/pages.yml
name: Publish

on:
  push:
    branches: [main]

jobs:
  publish:
    # Pick a label that ships Node. `docker` is the Docker-in-Docker image and
    # has none, so actions such as actions/checkout cannot start on it.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      # Use your favourite site generator here. Anything that writes the
      # finished site into a directory will do.
      - run: npm ci && npm run build

      - name: Push the built site to the pages branch
        working-directory: dist
        env:
          TOKEN: ${{ secrets.FORGEJO_TOKEN }}
          SERVER_URL: ${{ forgejo.server_url }}
          REPOSITORY: ${{ forgejo.repository }}
          SHA: ${{ forgejo.sha }}
        run: |
          git init -b pages
          git config user.name "forgejo-actions"
          git config user.email "forgejo-actions@noreply.codefloe.com"
          git add -A
          git commit -m "deploy ${SHA}"
          remote="${SERVER_URL/:\/\//://x-access-token:${TOKEN}@}/${REPOSITORY}.git"
          git push --force "$remote" pages

Set working-directory to whatever directory your generator writes into: dist, public, _site, build. The branch is force-pushed each time, so it holds the current site rather than a commit per build, and the commit message records which source revision produced it.

You get the full build log, like any other workflow, you choose the toolchain and its versions, and the branch always shows exactly what is being served.

Publishing more branches

Section titled “Publishing more branches”

Besides its main branch, a repository can publish up to five more branches, each at its own address. Use it to preview a development branch before merging it, or to serve docs and a demo from the same repository.

Each additional branch is served at the repository’s address with @<branch> appended:

https://<username>.codefloe.page/<repository>@<branch>/

The main branch keeps its usual address, https://<username>.codefloe.page/<repository>/, without any suffix.

  1. Go to your repository’s Pages settings

  2. In the Additional branches section, select a branch

  3. Click Publish branch

The branch is published within a minute and republished on every push to it, exactly like the main branch. Deleting the branch unpublishes its site, and so does Unpublish in the settings. Disabling Pages unpublishes all of them.

A few things to keep in mind:

  • Only branch names made of letters, digits, ., _ and - can be published, because the branch becomes part of the address. A branch such as feature/login cannot, so publish its built output from a branch like preview-login instead.
  • Custom domains always serve the main branch.
  • Each additional branch is a separate site and counts towards the site size limit on its own.

To build a branch in Actions, use the workflow above with the branch names changed: trigger it on pushes to dev, and push the result to a branch such as pages-dev, which you then publish here.

Custom Domains

Section titled “Custom Domains”

A site can be served under a domain of your own. It takes a DNS record and the domain added in the repository’s Pages settings.

  1. Point the domain at CodeFloe

    Section titled “Point the domain at CodeFloe”

    For a subdomain such as www.example.com, create a CNAME record pointing at your subdomain on codefloe.page:

    www.example.com.  CNAME  techuser.codefloe.page.

    An apex domain such as example.com cannot be a CNAME. Either use your provider’s ALIAS or ANAME record type with the same target, or point A and AAAA records at CodeFloe directly:

    example.com.  A     142.132.154.74
example.com.  A     142.132.154.75
example.com.  A     142.132.154.80
example.com.  AAAA  2a01:4f8:261:2a16::2
example.com.  AAAA  2a01:4f8:261:2a14::2
example.com.  AAAA  2a01:4f8:261:2a0b::2

    Prefer ALIAS where you have it. The addresses above can change, and a record that follows the name keeps working when they do.

  2. Add the domain in CodeFloe

    Section titled “Add the domain in CodeFloe”

    1. Go to your repository’s Pages settings

    2. Add your domain in the Domains section

    3. Set it as the primary domain

    The DNS record decides which servers a visitor reaches. This step is what tells CodeFloe which repository the domain belongs to, so both are needed.

A certificate is issued once the record resolves, and renewed from then on. There is nothing to upload.

Your site is served at the root of a custom domain, not under /<repository>/, so the base path described above is not needed there.

You can add up to 20 domains. One of them has to be the primary, which is the address CodeFloe links to from the repository; the rest serve the same site.

Custom domains are optional, and removing the last one is allowed. Your codefloe.page address keeps working either way, so a site is never left without a way to reach it.

Next Steps

Section titled “Next Steps”