Configuration

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

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

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.GITHUB_TOKEN }}
          SERVER_URL: ${{ github.server_url }}
          REPOSITORY: ${{ github.repository }}
          SHA: ${{ github.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.

No secrets to manage

secrets.GITHUB_TOKEN is the job’s own automatic token. It is created for that run, scoped to that repository, and expires when the job ends. Nothing to create, store or rotate.

Switch Actions on first

Actions is off by default. Enable it in your repository settings, or the workflow above never runs.

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.

Set your base path

Your site is served under /<repository>/, not at the root of a domain. Most generators need configuration for this: set base (Astro, Vite), baseurl (Jekyll, Hugo) or site_url (MkDocs) to /<repository>/, or absolute links like /style.css will point above your site and 404.

Not needed for a repository named pages, or when you use your own domain, since both are served at a root.

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

   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.

   Caution

   Some DNS providers need the trailing ., and some add it for you. Check how yours writes the record.

   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

   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

• Technical Details - Learn about infrastructure and usage limits
• Forgejo Actions - Build your site before publishing it