From 9b655b9b370041dbcd20cc0f059f084bde752f4f Mon Sep 17 00:00:00 2001 From: Catherine Date: Sun, 5 Jul 2026 02:33:49 +0200 Subject: [PATCH] Add more explanation for git-pages/action `server:` option. (#826) Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/826 Reviewed-by: crystal Reviewed-by: Bastian Greshake Tzovaras --- content/codeberg-pages/forgejo-actions.md | 39 +++++++++++++++++-- content/codeberg-pages/using-custom-domain.md | 8 ++-- 2 files changed, 39 insertions(+), 8 deletions(-) diff --git a/content/codeberg-pages/forgejo-actions.md b/content/codeberg-pages/forgejo-actions.md index 3f1cb31..117568d 100644 --- a/content/codeberg-pages/forgejo-actions.md +++ b/content/codeberg-pages/forgejo-actions.md @@ -11,14 +11,44 @@ You can use any such tool you like: git-pages does not privilege any particular If you already use a static site generator and/or already use Forgejo Actions, using the pre-made Forgejo Action is by far the simplest and most efficient way to publish your site to Codeberg Pages. -To use it, simply add it as a final step to your workflow: +**If you use a `*.codeberg.page` subdomain,** +add the following step at the end of your workflow after replacing `repository-name` in the `site` parameter with the name of your repository: {% raw %} ```yaml - uses: https://codeberg.org/git-pages/action@v2 with: - site: 'https://${{ forge.repository_owner }}.codeberg.page/repository-name/' + site: https://${{ forge.repository_owner }}.codeberg.page/repository-name/ + token: ${{ forge.token }} + source: _site/ +``` + +{% endraw %} + +To publish a site to the root of your subdomain, `https://username.codeberg.page/`, ensure your repository is called `pages`, and add the following step instead: + +{% raw %} + +```yaml +- uses: https://codeberg.org/git-pages/action@v2 + with: + site: https://${{ forge.repository_owner }}.codeberg.page/ + token: ${{ forge.token }} + source: _site/ +``` + +{% endraw %} + +**If you use a custom domain,** +add the following step at the end of your workflow after replacing `yourdomain.com` with your custom domain: + +{% raw %} + +```yaml +- uses: https://codeberg.org/git-pages/action@v2 + with: + site: https://yourdomain.com/ server: codeberg.page token: ${{ forge.token }} source: _site/ @@ -26,8 +56,9 @@ To use it, simply add it as a final step to your workflow: {% endraw %} -Replace `repository-name` in the `site` parameter with the name of your repository. -If your repository is also called `pages`, you can also omit the repository name and deploy directly to the site `https://username.codeberg.page/`. +The `server` parameter directs the Action to upload your site to a specific git-pages server instead of resolving the A/AAAA records DNS records specified in the `site` parameter. It may be specified as `codeberg.page` anytime a site is published to Codeberg Pages, but is **required** for publishing a site on a custom domain for the first time. + +This is caused by a circular dependency: git-pages will not issue a TLS certificate unless a site exists on that domain, but contacting it over HTTPS is not possible unless a TLS certificate is obtained. When the `site` parameter is specified, the HTTPS connection is established with the specified server (`codeberg.page` in this case), and the custom domain is passed in the `Host:` header instead, breaking this loop. The `source` parameter should point to the directory (relative to the root, after all previous steps in your workflow) where your site generator has put the generated version of your site. This directory can also contain the `404.html` and `_redirects` files to customize your site’s behavior, as described in the [advanced documentation](/codeberg-pages/advanced-usage/). diff --git a/content/codeberg-pages/using-custom-domain.md b/content/codeberg-pages/using-custom-domain.md index 3eed61d..77a58f2 100644 --- a/content/codeberg-pages/using-custom-domain.md +++ b/content/codeberg-pages/using-custom-domain.md @@ -26,8 +26,8 @@ and configure it to serve content from Codeberg Pages. If you have a [CAA record](https://en.wikipedia.org/wiki/DNS_Certification_Authority_Authorization#Record) configured, you must [explicitly allow Let's Encrypt (staging) in your CAA record](https://letsencrypt.org/docs/caa/). -This means you need to add two extra CAA records. -The first record has a value of `letsencrypt.org;accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/292520050;validationmethods=tls-alpn-01,http-01`. +This means you need to add two extra CAA records. +The first record has a value of `letsencrypt.org;accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/292520050;validationmethods=tls-alpn-01,http-01`. The second record has a value of `letsencrypt.org;accounturi=https://acme-staging-v02.api.letsencrypt.org/acme/acct/272029763;validationmethods=tls-alpn-01,http-01`. If you're using [DNSSec](https://en.wikipedia.org/wiki/Domain_Name_System_Security_Extensions) on your custom domain, you might run into TLS certificate issues because `codeberg.page` doesn't use DNSSec at the moment. @@ -143,7 +143,7 @@ so keep an eye on Codeberg updates to check. -### Step 2: Configure Git-pages authorization +### Step 2: Configure git-pages authorization {% admonition "question" "Why do I need all these extra DNS records?" %} @@ -219,7 +219,7 @@ For technical reasons, the first deployment needs to go over HTTP and you need t After the first successful deployment you can change it to the `https://` scheme. **If you deploy from Forgejo Actions,** -the `site` parameter to the Git-pages action should be set to the URL of your custom domain. +the `site` parameter to the git-pages action should be set to the URL of your custom domain, and the `server` parameter should be set to `codeberg.page`. The [Forgejo Actions guide](/codeberg-pages/forgejo-actions/) includes example workflows and more information. ### Deploying to versions of your domain both with and without `www.`