TheCloud/hugoDocs
1
0
Fork 0
mirror of https://github.com/gohugoio/hugoDocs.git synced 2025-09-08 04:06:33 -04:00
Code Issues Packages Projects Releases Wiki Activity

content: Improve Codeberg Pages hosting instructions

Browse Source
This commit is contained in:
Joe Mooring 2025-07-21 08:30:46 -07:00
parent 794477792d
commit b5b24750cf
2 changed files with 22 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.cspell.json
View File

@ -89,6 +89,7 @@
"struct",
"toclevels",
"unmarshal",
"unmarshaled",
"unpublishdate",
"zgotmplz",
"# ----------------------------------------------------------------------",
@ -143,10 +144,11 @@
"cifs",
"corejs",
"disqus",
"doas",
"docutils",
"dpkg",
"doas",
"eopkg",
"forgejo",
"gitee",
"goldmark",
"katex",

33
content/en/host-and-deploy/host-on-codeberg-pages.md
View File

@ -51,9 +51,11 @@ git remote add origin https://codeberg.org/<YourUsername>/pages.git
git push -u origin main
```
## Automated deployment using Woodpecker CI
## Automated deployment
There are two methods you can use to deploy your Hugo website to Codeberg automatically. These are: Woodpecker CI and Forgejo Actions.
You can automatically deploy your Hugo website to Codeberg using one of two methods: Woodpecker CI or Forgejo Actions.
### Woodpecker CI
To use Codeberg's Woodpecker CI, you need to have or [request] access to it, as well as add a `.woodpecker.yaml` file in the root of your project. A template and additional instructions are available in the official [examples repository].
@ -78,7 +80,7 @@ git push -u origin main
Your project will then be built and deployed by Codeberg's Woodpecker CI.
## Automated deployment using Forgejo Actions
### Forgejo Actions
The other way to deploy your website to Codeberg pages automatically is to make use of Forgejo Actions. Actions need a _runner_ to work, and Codeberg has [great documentation] on how to set one up yourself. However, Codeberg provides a [handful of humble runners] themselves (they say this feature is in "open alpha"), which actually seem powerful enough to build at least relatively simple websites.
@ -160,21 +162,25 @@ jobs:
The second file implements a more complex scenario: having your website sources in one repository and the resulting static website in another repository (in this case, `pages`). If you want Codeberg to make your website available at the root of your pages subdomain (`https://<YourUsername>.codeberg.page/`), you have to push that website to the default branch of your repository named `pages`.
Since this action involves more than one repository, it will require a bit more preparation:
1. Create the target repository. Name it `pages`.
2. Generate a new SSH key. *Do not* use any of your own SSH keys for this, but generate one for this specific task only. On Linux, BSD, and, likely, other operating systems, you can open a terminal emulator and run the following command to generate the key:
```shell
ssh-keygen -f pagesbuild -P ""
```
This will generate two files in your current directory: `pagesbuild` (private key) and `pagesbuild.pub` (public key).
3. Add the newly generated public key as a deploy key to your `pages` repository: navigate to its Settings, click on "Deploy keys" in the left menu, click the "Add deploy key" button, give it a name (e.g. "Actions deploy key"), paste the contents of the **public** key file (`pagesbuild.pub`) to the Content field, tick the "Enable write access" checkbox, then submit the form.
4. Navigate back to your source repository settings, expand the "Actions" menu and click on "Secrets". Then click "Add Secret", enter "DEPLOY_KEY" as the secret name and paste the contents of the newly generated **private** key file (`pagesbuild`) into the Value field.
5. Navigate to the "Variables" submenu of the "Actions" menu and add the following variables:
| Name | Value |
|---------------------|----------------------------------------------------------------------------------|
| `TARGET_REPOSITORY` | `<YourUsername>/pages` |
| `TARGET_BRANCH` | `main` (enter the default branch name of the `pages` repo here) |
| `SSH_KNOWN_HOSTS` | (paste the output you get by running `ssh-keyscan codeberg.org` in the terminal) |
Name|Value
:--|:--
`TARGET_REPOSITORY`|`<YourUsername>/pages`
`TARGET_BRANCH`|`main` (enter the default branch name of the `pages` repo here)
`SSH_KNOWN_HOSTS`|(paste the output you get by running `ssh-keyscan codeberg.org` in the terminal)
Once you've done all of the above, commit the following file to your repository as `.forgejo/workflows/hugo.yaml`. As you can see, the `deploy` job of this workflow is slightly different from the file above:
@ -249,13 +255,13 @@ jobs:
Once you commit one of the two files to your website source repository, you should see your first automated build firing up pretty soon. You can also trigger it manually by navigating to the **Actions** section of your repository web page, choosing **hugo.yaml** on the left and clicking on **Run workflow**.
### Using custom domain with Forgejo Actions
## Forgejo Actions custom domains
Codeberg Pages utilizes `.domains` file to identify allowed domains for a specific branch. It's necessary to ensure that the `.domains` file is located in the root directory of output repository or branch instead of root directory of source files.
Codeberg Pages relies on a `.domains` file to identify allowed domains for a specific branch. It's important that this file is located in the root directory of your output repository or branch, rather than in the root directory of your source files. To achieve this, simply place your `.domains` file in the `static` directory of your project. When your site is built, it will be automatically copied to the `public` directory, which serves as the root of your output.
The ideal practice is putting your `.domains` file in `static` folder, and it will be preserved without modification in `public` folder, which will be the root directory of the output repository or branch.
When looking at the example `.forgejo/workflows/hugo.yaml`, you'll notice that the `upload-artifact@v3` action is used to upload the public directory to the deployment branch. By default, both `upload-artifact@v3` and `upload-artifact@v4` exclude all dot files from being uploaded unless you specifically tell them not to (you can find more details [here]). To make sure dot files are included, modify your workflow like this:
Nevertheless, it's worth noticing that in the example `.forgejo/workflows/hugo.yaml`, the action `upload-artifact@v3` , has been used to upload `public` folder to the target branch for deploy. And by default, [upload-artifact@v3 and @v4 exclude all dot files from uploading unless you explicitly prevents it from doing so](https://github.com/actions/upload-artifact/issues/602):
[here]: https://github.com/actions/upload-artifact/issues/602
```yaml {file=".forgejo/workflows/hugo.yaml" copy=true}
- name: Upload generated files
@ -266,8 +272,7 @@ Nevertheless, it's worth noticing that in the example `.forgejo/workflows/hugo.y
include-hidden-files: true # Prevents excluding .domains from uploading
```
It is important to modify the workflow file accordingly if you are using a custom domain.
If you're using a custom domain, it's important to update your workflow file accordingly.
## Other resources