dallasgroot/Documentation
1
0
Fork 0
mirror of https://codeberg.org/Codeberg/Documentation.git synced 2026-08-15 14:53:29 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add more explanation for git-pages/action server: option. (#826)

Browse source 
Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/826
Reviewed-by: crystal <crystal@noreply.codeberg.org>
Reviewed-by: Bastian Greshake Tzovaras <gedankenstuecke@noreply.codeberg.org>
This commit is contained in:
Catherine 2026-07-05 02:33:49 +02:00 committed by Bastian Greshake Tzovaras
parent 33094726bb
commit 9b655b9b37
2 changed files with 39 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
content/codeberg-pages/forgejo-actions.md
View file

@ -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/).

8
content/codeberg-pages/using-custom-domain.md
View file

@ -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.
</tbody>
</table>
### 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.`