Update documentation (README, Forgejo Actions) #667

askaaron commented 2025年08月22日 20:23:19 +02:00

Changes in this PR:

1. Updated README.md to explain how to do linting and use prettier.
2. Updated "Using Forgejo Actions (Self-hosted)":
   1. Explain how to get the Runner version as separate section.
   2. Clarify the two options how to start the Runner and separate configuration and registration.
   3. Fix the section about using Docker-in-Docker since this did not work as documented (the version also needs to be specified).
3. Fixed linting issues.

Changes in this PR: 1. Updated README.md to explain how to do linting and use prettier. 2. Updated "Using Forgejo Actions (Self-hosted)": 1. Explain how to get the Runner version as separate section. 2. Clarify the two options how to start the Runner and separate configuration and registration. 3. Fix the section about using Docker-in-Docker since this did not work as documented (the version also needs to be specified). 3. Fixed linting issues.

renovate-bot commented 2025年08月23日 01:26:18 +02:00

Surge PR preview deployment succeeded. View it at https://Codeberg-Documentation-pr-667.surge.sh

<!--woodpeckerci-plugin-surge-preview--> Surge PR preview deployment succeeded. View it at https://Codeberg-Documentation-pr-667.surge.sh

askaaron commented 2025年08月23日 02:41:31 +02:00

The linting errors should now be fixed.

The linting errors should now be fixed.

gedankenstuecke commented 2025年08月25日 01:19:19 +02:00

Thanks! It seems there's still a few failing bits, but we can get to those once someone had a review for the content (please bear with us, as the northern hemisphere is in its summer vacation mode, things tend to be a bit slower at times :))

Thanks! It seems there's still a few failing bits, but we can get to those once someone had a review for the content (please bear with us, as the northern hemisphere is in its summer vacation mode, things tend to be a bit slower at times :))

askaaron commented 2025年08月25日 09:45:46 +02:00

@gedankenstuecke wrote in #667 (comment):

Thanks! It seems there's still a few failing bits, but we can get to those once someone had a review for the content (please bear with us, as the northern hemisphere is in its summer vacation mode, things tend to be a bit slower at times :))

I see - there is a rule, that links without descriptive text are not allowed, I fixed the affected link.

I also added the linter command to README.md, so this can be done before committing anything. Maybe this should be scripts which can be called by the Forgejo action as well, so there is only one place to maintain.

Edit: the linter also reports one unknown word getent which is part of a script. I don't know, if this will prevent a sucessful build. But if this is the case, there should also be a documenation how to add unknown words or how to tell the linter to ignore code blocks.

$ pnpx cspell lint --no-progress --gitignore '{**,.*}/{*,.*}'
content/ci/actions.md:183:14 - Unknown word (getent)
CSpell: Files checked: 79, Issues found: 1 in 1 file.

Edit: I found .cspell.json and fixed this problem by adding getent as new word and the shell dictionary and to CSpell to void future issues with shell commands which may also become part of the documentation.

@gedankenstuecke wrote in https://codeberg.org/Codeberg/Documentation/pulls/667#issuecomment-6698041: > Thanks! It seems there's still a few failing bits, but we can get to those once someone had a review for the content (please bear with us, as the northern hemisphere is in its summer vacation mode, things tend to be a bit slower at times :)) I see - there is a rule, that links without descriptive text are not allowed, I fixed the affected link. I also added the linter command to README.md, so this can be done **before** committing anything. Maybe this should be scripts which can be called by the Forgejo action as well, so there is only one place to maintain. Edit: the linter also reports one unknown word `getent` which is part of a script. I don't know, if this will prevent a sucessful build. But if this is the case, there should also be a documenation how to add unknown words or how to tell the linter to ignore code blocks. ``` $ pnpx cspell lint --no-progress --gitignore '{**,.*}/{*,.*}' content/ci/actions.md:183:14 - Unknown word (getent) CSpell: Files checked: 79, Issues found: 1 in 1 file. ``` Edit: I found `.cspell.json` and fixed this problem by adding `getent` as new word and the `shell` dictionary and to CSpell to void future issues with shell commands which may also become part of the documentation.

askaaron commented 2025年08月30日 15:22:23 +02:00

Just for the records - for me everything works fine, so maybe we want to let the checks run again:

$ npx prettier . -c
Checking formatting...
All matched files use Prettier code style!
$ pnpx cspell lint --no-progress --gitignore '{**,.*}/{*,.*}'
Packages: +110
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 110, reused 105, downloaded 5, added 110, done
CSpell: Files checked: 79, Issues found: 0 in 0 files.

Just for the records - for me everything works fine, so maybe we want to let the checks run again: ``` $ npx prettier . -c Checking formatting... All matched files use Prettier code style! $ pnpx cspell lint --no-progress --gitignore '{**,.*}/{*,.*}' Packages: +110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Progress: resolved 110, reused 105, downloaded 5, added 110, done CSpell: Files checked: 79, Issues found: 0 in 0 files. ```

gedankenstuecke commented 2025年08月30日 16:48:23 +02:00

I nudged the CI to run again, but I also still hope that someone with Forgejo actions expertise can give it a read (ping @n0toose)

I nudged the CI to run again, but I also still hope that someone with Forgejo actions expertise can give it a read (ping @n0toose)

Gusted commented 2025年09月01日 08:59:51 +02:00

There might be a difference because the linter seems to run a older version, lets not worry too much about it.

There might be a difference because the linter seems to run a older version, lets not worry too much about it.

fnetX commented 2025年10月05日 02:36:41 +02:00

@askaaron Could you fix the merge conflict?

@askaaron Could you fix the merge conflict?

askaaron commented 2025年10月05日 10:50:23 +02:00

@fnetX wrote in #667 (comment):

@askaaron Could you fix the merge conflict?

I updated my branch with the upstream and fixed the conflict.

@fnetX wrote in https://codeberg.org/Codeberg/Documentation/pulls/667#issuecomment-7545082: > @askaaron Could you fix the merge conflict? I updated my branch with the upstream and fixed the conflict.

n0toose commented 2025年10月20日 08:29:35 +02:00

@askaaron Looks good to me apart from the need to run Prettier again. Thanks for the additional README updates :)

I can take care of that later if you want me to.

@askaaron Looks good to me apart from the need to run Prettier again. Thanks for the additional README updates :) I can take care of that later if you want me to.

askaaron commented 2025年10月20日 10:26:18 +02:00

@n0toose wrote in #667 (comment):

@askaaron Looks good to me apart from the need to run Prettier again. Thanks for the additional README updates :)

I can take care of that later if you want me to.

I did run prettier. So I don't get it, what is missing. Is the build pipeline differnt from what I documented what to run manually?

@n0toose wrote in https://codeberg.org/Codeberg/Documentation/pulls/667#issuecomment-7811453: > @askaaron Looks good to me apart from the need to run Prettier again. Thanks for the additional README updates :) > > I can take care of that later if you want me to. I did run prettier. So I don't get it, what is missing. Is the build pipeline differnt from what I documented what to run manually?

askaaron commented 2025年10月20日 10:28:14 +02:00

@n0toose wrote in #667 (comment):

@askaaron Looks good to me apart from the need to run Prettier again. Thanks for the additional README updates :)

I can take care of that later if you want me to.

I just checked it - no changes here with prettier:

pnpx prettier . -c
Packages: +1
+
Progress: resolved 1, reused 1, downloaded 0, added 1, done
Checking formatting...
All matched files use Prettier code style!

So I assume, the build pipeline does something different.

@n0toose wrote in https://codeberg.org/Codeberg/Documentation/pulls/667#issuecomment-7811453: > @askaaron Looks good to me apart from the need to run Prettier again. Thanks for the additional README updates :) > > I can take care of that later if you want me to. I just checked it - no changes here with prettier: ``` pnpx prettier . -c Packages: +1 + Progress: resolved 1, reused 1, downloaded 0, added 1, done Checking formatting... All matched files use Prettier code style! ``` So I assume, the build pipeline does something different.

gedankenstuecke commented 2025年10月20日 14:13:07 +02:00

@askaaron That's strange, this is what happened for me when running it on your branch:

❯ npx prettier . -c
Checking formatting...
[warn] content/ci/agents.md
[warn] content/codeberg-pages/using-custom-domain.md
[warn] content/security/ssh-key.md
[warn] Code style issues found in 3 files. Run Prettier with --write to fix.

After running npx prettier . --write, this is how the diff for one of the files looks like:

diff --git a/content/ci/agents.md b/content/ci/agents.md
index db614ca..5c600f9 100644
--- a/content/ci/agents.md
+++ b/content/ci/agents.md
@@ -24,8 +24,10 @@ Before deploying the agent, you need to obtain an agent token from Codeberg's Wo
 To do so, please follow the instructions immediately below for users, and follow the instructions below that f
or organizations.
 1. Go to the agents page
+
 1. For users, go to the [Codeberg Woodpecker CI User Agent settings](https://ci.codeberg.org/user/agents)
 2. For organizations:
+
 1. Go to the [Codeberg Woodpecker CI Repos Page](https://ci.codeberg.org/)
 2. Click on a repository in the organization you're adding the agent to.
 3. Click on the organization name in the top left.

@askaaron That's strange, this is what happened for me when running it on your branch: ``` ❯ npx prettier . -c Checking formatting... [warn] content/ci/agents.md [warn] content/codeberg-pages/using-custom-domain.md [warn] content/security/ssh-key.md [warn] Code style issues found in 3 files. Run Prettier with --write to fix. ``` After running `npx prettier . --write`, this is how the diff for one of the files looks like: ```diff diff --git a/content/ci/agents.md b/content/ci/agents.md index db614ca..5c600f9 100644 --- a/content/ci/agents.md +++ b/content/ci/agents.md @@ -24,8 +24,10 @@ Before deploying the agent, you need to obtain an agent token from Codeberg's Wo To do so, please follow the instructions immediately below for users, and follow the instructions below that f or organizations. 1. Go to the agents page + 1. For users, go to the [Codeberg Woodpecker CI User Agent settings](https://ci.codeberg.org/user/agents) 2. For organizations: + 1. Go to the [Codeberg Woodpecker CI Repos Page](https://ci.codeberg.org/) 2. Click on a repository in the organization you're adding the agent to. 3. Click on the organization name in the top left. ```

askaaron commented 2025年10月20日 16:34:36 +02:00

@gedankenstuecke wrote in #667 (comment):

@askaaron That's strange, this is what happened for me when running it on your branch:

❯ npx prettier . -c
Checking formatting...
[warn] content/ci/agents.md
[warn] content/codeberg-pages/using-custom-domain.md
[warn] content/security/ssh-key.md
[warn] Code style issues found in 3 files. Run Prettier with --write to fix.

No - I don't have this. Also the changes in content/codeberg-pages/using-custom-domain.md are done by the prettier, not by myself.

So there is a problem here: when you clone the repo and install the tools as suggested, they don't work as expected. Maybe because of different package versions? The files as I comitted them are after I used the prettier locally on my side.

Also the instructions for the Dockerfile don't work. The repository name must be in lowercase - codeberg/documentation-server and not Codeberg/Documentation-server and the build fails:

1.581 Reading package lists...
1.587 W: The repository 'http://security.debian.org/debian-security stretch/updates Release' does not have a Release file.
1.587 W: The repository 'http://deb.debian.org/debian stretch Release' does not have a Release file.
1.587 W: The repository 'http://deb.debian.org/debian stretch-updates Release' does not have a Release file.
1.587 E: Failed to fetch http://security.debian.org/debian-security/dists/stretch/updates/main/binary-amd64/Packages 404 Not Found [IP: 151.101.130.132 80]
1.587 E: Failed to fetch http://deb.debian.org/debian/dists/stretch/main/binary-amd64/Packages 404 Not Found
1.587 E: Failed to fetch http://deb.debian.org/debian/dists/stretch-updates/main/binary-amd64/Packages 404 Not Found
1.587 E: Some index files failed to download. They have been ignored, or old ones used instead.
------
Dockerfile:3
--------------------
 1 | FROM node:16.15.1-stretch-slim
 2 |
 3 | >>> RUN apt-get update && apt-get -y upgrade
 4 |
 5 | RUN apt-get install -y git curl
--------------------
ERROR: failed to build: failed to solve: process "/bin/sh -c apt-get update && apt-get -y upgrade" did not complete successfully: exit code: 100

@gedankenstuecke wrote in https://codeberg.org/Codeberg/Documentation/pulls/667#issuecomment-7815530: > @askaaron That's strange, this is what happened for me when running it on your branch: > > ```text > ❯ npx prettier . -c > Checking formatting... > [warn] content/ci/agents.md > [warn] content/codeberg-pages/using-custom-domain.md > [warn] content/security/ssh-key.md > [warn] Code style issues found in 3 files. Run Prettier with --write to fix. > ``` No - I don't have this. Also the changes in `content/codeberg-pages/using-custom-domain.md` are done by the prettier, not by myself. So there is a problem here: when you clone the repo and install the tools as suggested, they don't work as expected. Maybe because of different package versions? The files as I comitted them are after I used the prettier locally on my side. Also the instructions for the Dockerfile don't work. The repository name must be in lowercase - `codeberg/documentation-server ` and not `Codeberg/Documentation-server` and the build fails: ``` 1.581 Reading package lists... 1.587 W: The repository 'http://security.debian.org/debian-security stretch/updates Release' does not have a Release file. 1.587 W: The repository 'http://deb.debian.org/debian stretch Release' does not have a Release file. 1.587 W: The repository 'http://deb.debian.org/debian stretch-updates Release' does not have a Release file. 1.587 E: Failed to fetch http://security.debian.org/debian-security/dists/stretch/updates/main/binary-amd64/Packages 404 Not Found [IP: 151.101.130.132 80] 1.587 E: Failed to fetch http://deb.debian.org/debian/dists/stretch/main/binary-amd64/Packages 404 Not Found 1.587 E: Failed to fetch http://deb.debian.org/debian/dists/stretch-updates/main/binary-amd64/Packages 404 Not Found 1.587 E: Some index files failed to download. They have been ignored, or old ones used instead. ------ Dockerfile:3 -------------------- 1 | FROM node:16.15.1-stretch-slim 2 | 3 | >>> RUN apt-get update && apt-get -y upgrade 4 | 5 | RUN apt-get install -y git curl -------------------- ERROR: failed to build: failed to solve: process "/bin/sh -c apt-get update && apt-get -y upgrade" did not complete successfully: exit code: 100 ```

Gusted commented 2025年10月20日 16:36:52 +02:00

I will take care of the linter problem.

I will take care of the linter problem.

askaaron commented 2025年10月20日 16:40:50 +02:00

I now check, what happens, if I change content/ci/agents.md as suggested by your own prettier run.

Now prettier wants to change this back here!

Before (as suggested by your prettier):

 To do so, please follow the instructions immediately below for users, and follow the instructions below that f
or organizations.
 1. Go to the agents page
 1. For users, go to the [Codeberg Woodpecker CI User Agent settings](https://ci.codeberg.org/user/agents)
 2. For organizations:
 1. Go to the [Codeberg Woodpecker CI Repos Page](https://ci.codeberg.org/)
 2. Click on a repository in the organization you're adding the agent to.
 3. Click on the organization name in the top left.

And after I run pnpx prettier . --write here:

 To do so, please follow the instructions immediately below for users, and follow the instructions below that f
or organizations.
 1. Go to the agents page
 1. For users, go to the [Codeberg Woodpecker CI User Agent settings](https://ci.codeberg.org/user/agents)
 2. For organizations:
 1. Go to the [Codeberg Woodpecker CI Repos Page](https://ci.codeberg.org/)
 2. Click on a repository in the organization you're adding the agent to.
 3. Click on the organization name in the top left.

So we have a problem here. prettier does not work as expected everywhere. We should fix this.

Also it makes no sense to add blank lines in a numbered list just because a new level begins.

I now check, what happens, if I change `content/ci/agents.md` as suggested by your own prettier run. Now prettier wants to change this back here! Before (as suggested by your prettier): ``` To do so, please follow the instructions immediately below for users, and follow the instructions below that f or organizations. 1. Go to the agents page 1. For users, go to the [Codeberg Woodpecker CI User Agent settings](https://ci.codeberg.org/user/agents) 2. For organizations: 1. Go to the [Codeberg Woodpecker CI Repos Page](https://ci.codeberg.org/) 2. Click on a repository in the organization you're adding the agent to. 3. Click on the organization name in the top left. ``` And after I run `pnpx prettier . --write` here: ``` To do so, please follow the instructions immediately below for users, and follow the instructions below that f or organizations. 1. Go to the agents page 1. For users, go to the [Codeberg Woodpecker CI User Agent settings](https://ci.codeberg.org/user/agents) 2. For organizations: 1. Go to the [Codeberg Woodpecker CI Repos Page](https://ci.codeberg.org/) 2. Click on a repository in the organization you're adding the agent to. 3. Click on the organization name in the top left. ``` So we have a problem here. prettier does not work as expected everywhere. We should fix this. Also it makes no sense to add blank lines in a numbered list just because a new level begins.

Gusted commented 2025年10月20日 18:54:27 +02:00

The prettier version was outdated, it should be fixed with Codeberg/Documentation#686. Renovate will now take care of keeping that version up to date.

The prettier version was outdated, it should be fixed with Codeberg/Documentation#686. Renovate will now take care of keeping that version up to date.