From 65f556b638c06830112ce9a3b765daddd146068c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Emmanuel=20BENO=C3=8ET?= Date: Wed, 24 Jul 2024 05:41:53 +0000 Subject: [PATCH] admin: more details about action runner offline registration (#769) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR - adds more details regarding the nature of the secret used when registering runners offline using `forgejo-cli actions register`, - explains how to change the secret for an existing runner ([Forgejo PR #4619](https://codeberg.org/forgejo/forgejo/pulls/4619)), - explains how to keep the Forgejo-side command idempotent if the labels aren't known ([Forgejo PR #4610](https://codeberg.org/forgejo/forgejo/pulls/4610)) Reviewed-on: https://codeberg.org/forgejo/docs/pulls/769 Reviewed-by: twenty-panda Co-authored-by: Emmanuel BENOÎT Co-committed-by: Emmanuel BENOÎT --- docs/admin/actions.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/admin/actions.md b/docs/admin/actions.md index fe285473..da78cb3d 100644 --- a/docs/admin/actions.md +++ b/docs/admin/actions.md @@ -339,6 +339,26 @@ The `Forgejo runner` needs to connect to a `Forgejo` instance and must be regist --secret 7c31591e8b67225a116d4a4519ea8e507e08f71f ``` + The secret must be a 40-character long string of hexadecimal numbers. + The first 16 characters will be used as an identifier for the runner, while + the rest is the actual secret. It is possible to update the secret of an + existing runner by running the command again on the Forgejo machine, with + the last 24 characters updated. + + For instance, the command below would change the secret set by the previous + command: + + ```sh + $ forgejo forgejo-cli actions register --name runner-name --scope myorganization \ + --secret 7c31591e8b67225a84e8e06633b9578e793664c3 + # ^^^^^^^^^^^^^^^^ This part is identical + ``` + + The registration command on the Forgejo side is mostly idempotent, with the + exception of the runner labels. If the command is run without `--labels`, they + will be reset, and the runner won't set them back until it is restarted. The + `--keep-labels` option can be used to preserve the existing labels. + ### Configuration The default configuration for the runner can be