agent-orchestrator/skills/codeberg-pages/SKILL.md

name, description

name

description

codeberg-pages

Publish a static site to Codeberg Pages, including custom domains on the new "git-pages" server. Use when deploying a site to Codeberg Pages, setting up or debugging a codeberg.page / custom-domain deployment, wiring the DNS records (A/AAAA, CNAME), the _git-pages-repository TXT authorization record, or the deploy webhook — or when a custom domain serves a TLS error / never gets a certificate. Covers the 2025→2026 migration off the old Pages Server v2 (.domains file) to git-pages (webhook + TXT authorization).

Publishing a site to Codeberg Pages

Codeberg Pages migrated from the old Pages Server v2 (automatic deploy, .domains file) to the new git-pages server. On git-pages a deployment is webhook-triggered and a custom domain is authorized by a TXT record, not by a file in the repo. If you're following older docs or a .domains-based deploy.sh, that's why things silently don't work.

All values below were verified against the official docs (https://docs.codeberg.org/codeberg-pages/ and .../using-custom-domain/). Codeberg changes these; re-check the docs if something behaves unexpectedly.

The mental model

1. Static site content lives on a branch named pages (per-repo site) — push your built site there.
2. On git-pages, pushing alone does not deploy. A webhook on the repo, pointed at the domain you want, is what triggers a deployment.
3. A custom domain is bound to the repo by a TXT authorization record (_git-pages-repository.<domain>) plus the normal A/AAAA/CNAME records.
4. TLS (Let's Encrypt) is issued only after the first successful deployment. Before that, browsers show a TLS error — that is expected, not a bug.

Basic deploy (no custom domain, *.codeberg.page)

• Put the site on a pages branch and push it.
• Add a webhook: repo Settings → Webhooks → Forgejo, Target URL https://<username>.codeberg.page/<repository>/, Branch filter: pages.
• (User/org site: name the repo pages and use Target URL https://<username>.codeberg.page/.)

Custom domain setup (git-pages)

Do all four. Missing #2 or #3 is the usual cause of "DNS looks right but the site won't serve / no certificate."

1. DNS: point the domain at Codeberg

Exact values (verify against the docs — Codeberg has changed IPs before):

• Apex domain (example.org):
  • A → 217.197.84.141
  • AAAA → 2a0a:4580:103f:c0de::2
• Subdomain (www.example.org, foo.example.org):
  • CNAME → codeberg.page. ← note the trailing dot.

Trailing-dot trap: in a zone file / most DNS UIs, a CNAME target without a trailing dot is treated as relative and the zone is appended — e.g. entering codeberg.page (or an old <user>.codeberg.page) can resolve to codeberg.page.example.org., which is broken. Always use the fully-qualified codeberg.page. with the dot. (ALIAS/ANAME works where CNAME isn't allowed, but conflicts with DNSSEC-signed zones.)

2. TXT authorization record (this is how git-pages maps domain → repo)

Create one per domain you serve:

_git-pages-repository.example.org.   TXT   "https://codeberg.org/<user>/<repo>.git"

• Name: the _git-pages-repository. prefix on the exact domain (including each subdomain you serve — apex and www each need their own if both are used).
• Value: the HTTPS clone URL of the repo, ending in .git.
• (If you deploy via Forgejo Actions instead of a webhook, the record is _git-pages-forge-allowlist.<domain> with the same clone-URL value.)

3. Deploy webhook (per domain)

Repo Settings → Webhooks → Forgejo:

• Target URL: the domain itself, and http:// (not https://) for the first deployment — this is documented, not a mistake (the cert doesn't exist yet). One webhook per domain, e.g. http://example.org, http://foo.example.org.
• Branch filter: pages.
• After the first successful deploy and cert issuance, you may switch the Target URLs to https://.

4. Trigger the first deploy

Push to the pages branch (re-run your deploy script / git push origin pages). The push fires the webhook, git-pages pulls and deploys, then requests a Let's Encrypt certificate.

• Do NOT rely on the webhook "Test delivery" button — the official docs say it fails by design and is not a valid way to verify or trigger a deploy. Verify by pushing and then checking the webhook's recent-deliveries log, or just load the site. (This corrects a common misconception that "Test delivery" triggers a deploy.)

The .domains file is obsolete

Under the old Pages Server v2, a .domains file in the branch listed the domains and did apex-vs-alias redirects. On git-pages it is no longer used — authorization comes from the TXT record. It's harmless to leave, but you can delete it (and drop any .domains handling from deploy.sh). Bonus: on git-pages each domain gets its own deployment, so a second domain serves the site directly instead of 301-redirecting to the primary as the old .domains system did.

TLS / certificate notes

• A cert is issued only after the first successful webhook deployment. A TLS error before that is expected.
• If the domain has CAA records, they must allow Let's Encrypt (including the staging issuer) or the cert request is refused.
• Cert still never issues after a successful deploy → confirm the _git-pages-repository TXT value exactly matches the repo's HTTPS .git URL, and that the webhook Target URL matches the domain.

Quick troubleshooting checklist

• Browser TLS error, no cert → no successful deploy yet. Check webhook deliveries; push to pages; confirm webhook Target URL used http:// for the first deploy.
• "DNS is correct but site won't serve" → missing _git-pages-repository TXT, or missing/mis-branch-filtered webhook.
• CNAME resolves to codeberg.page.<yourzone> → missing trailing dot; set target to codeberg.page..
• CAA present → ensure Let's Encrypt is allowed.
• Old .domains behavior expected (redirects) → gone on git-pages; each domain now deploys independently.

Sources

• Codeberg Pages: https://docs.codeberg.org/codeberg-pages/
• Using custom domains: https://docs.codeberg.org/codeberg-pages/using-custom-domain/
• pages-server (now in maintenance, superseded by git-pages): https://codeberg.org/Codeberg/pages-server