mirror of
https://codeberg.org/Codeberg/Documentation.git
synced 2026-08-15 14:53:29 -07:00
9b655b9b37
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>
84 lines
3.9 KiB
Markdown
84 lines
3.9 KiB
Markdown
---
|
||
eleventyNavigation:
|
||
key: Deploying directly from Forgejo Actions
|
||
title: Deploying directly from Forgejo Actions
|
||
parent: CodebergPages
|
||
order: 100
|
||
---
|
||
|
||
Git-pages has an [associated Forgejo Action](https://codeberg.org/git-pages/action) that can be used to automatically deploy your website from a static site generation tool.
|
||
You can use any such tool you like: git-pages does not privilege any particular publishing system over others.
|
||
|
||
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.
|
||
|
||
**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/
|
||
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/
|
||
```
|
||
|
||
{% endraw %}
|
||
|
||
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/).
|
||
|
||
The `token` will automatically be filled by Forgejo Actions with a secret token, which in turn will automatically be recognized by git-pages as authorizing this workflow to publish to this site.
|
||
|
||
{% admonition "Warning" %}
|
||
|
||
If you use branches to test out new features, write draft blog posts, etc., you should either limit the whole workflow, or this step only, to pushes to a default branch (usually `main` or `master`) to ensure that only finalized content is published to your site.
|
||
|
||
To do this, either add a [`on.push.branches` list](https://forgejo.org/docs/latest/user/actions/reference/#onpush) to the whole workflow, or add [an `if` condition to the step](https://forgejo.org/docs/latest/user/actions/reference/#jobsjob_idstepsif-1) (or [to the whole job](https://forgejo.org/docs/latest/user/actions/reference/#jobsjob_idif)) like this:
|
||
|
||
{% raw %}
|
||
|
||
```yaml
|
||
if: ${{ forge.ref == 'refs/heads/main'}}
|
||
```
|
||
|
||
{% endraw %}
|
||
|
||
This will limit deploys so they only happen when CI is triggered by a push to the `main` branch.
|
||
|
||
{% endadmonition %}
|