Deploy Astro to Forgejo Pages

Astro works well as a static build: install dependencies, build to `dist`, then publish the output from a workflow.

Pages

What this solves

You want an Astro site or documentation project deployed from a Forgejo repository.

Best fit

Marketing sites
Project docs
Static content with preview workflows

How to think about it

Astro deployments are usually a clean static-site case. The important details are the Node version, package manager, output directory, and whether the site is served at a domain root or a subpath.

Astro build job

name: pages
on: [push]

jobs:
  build:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm run build
      - run: test -d dist

Practical path

01 Add an Actions workflow that installs Node and runs your Astro build.
02 Publish the generated `dist` directory with the Pages deploy action.
03 Attach a custom domain once the deployment path is stable.

When to choose another path

Set Astro base configuration if the site is not served from the domain root.

Fail the workflow when generated links or assets are missing.

Add the custom domain after the default Pages URL is known-good.

Next resources

Pages docs

How Fjord Pages deploys static sites.

Actions docs

Workflow basics for deploy jobs.

CLI

Trigger and inspect deploy workflows.

Operations

Run the forge behind the site calmly.