mirror of
https://gitea.com/gitea/docs.git
synced 2026-09-17 19:55:34 +00:00
Add runner 2 and 3 documentations (#488)
Reviewed-on: https://gitea.com/gitea/docs/pulls/488 Reviewed-by: silverwind <[email protected]>
This commit is contained in:
Lunny Xiao
Executable
+196
@@ -0,0 +1,196 @@
|
||||
#!/bin/bash
|
||||
#
|
||||
# Regenerates the generated pages of the runner documentation from the runner
|
||||
# source: the command line reference and the example configuration file.
|
||||
#
|
||||
# Usage:
|
||||
#
|
||||
# ./update_runner_docs.sh develop docs, from the main branch
|
||||
# ./update_runner_docs.sh --released every documented release series
|
||||
# ./update_runner_docs.sh <git ref> <dir> one ref into one directory
|
||||
#
|
||||
# --released needs no version list: the documented series are the
|
||||
# runner-docs_versioned_docs/version-<series>/reference directories, and the tag
|
||||
# each one is generated from is the newest stable v<series>.x.y tag of
|
||||
# gitea/runner, looked up through the Gitea API. A new series is documented by
|
||||
# running `pnpm run docusaurus docs:version:runner-docs <series>`, nothing here
|
||||
# has to be edited.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
RUNNER_REMOTE="${RUNNER_REMOTE:-https://gitea.com/gitea/runner.git}"
|
||||
RUNNER_API="${RUNNER_API:-https://gitea.com/api/v1/repos/gitea/runner}"
|
||||
VERSIONED_DOCS="runner-docs_versioned_docs"
|
||||
SRC_DIR=".tmp/upstream-runner"
|
||||
BIN="$PWD/.tmp/gitea-runner"
|
||||
TAGS_FILE=".tmp/runner-tags.txt"
|
||||
|
||||
mkdir -p .tmp
|
||||
|
||||
# prints every tag name of the runner repository, one per line
|
||||
list_runner_tags() {
|
||||
local page=1 names
|
||||
while :; do
|
||||
names="$(curl --silent --show-error --fail \
|
||||
"$RUNNER_API/tags?limit=50&page=$page" |
|
||||
grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d '"' -f 4)"
|
||||
[ -n "$names" ] || return 0
|
||||
printf '%s\n' "$names"
|
||||
page=$((page + 1))
|
||||
done
|
||||
}
|
||||
|
||||
# latest_stable_tag <series>, e.g. "3" -> "v3.0.2", empty if the series has no
|
||||
# release yet. Pre-release tags (v3.0.0-rc1) are ignored on purpose.
|
||||
latest_stable_tag() {
|
||||
local series="$1"
|
||||
if [ ! -s "$TAGS_FILE" ]; then
|
||||
list_runner_tags > "$TAGS_FILE"
|
||||
fi
|
||||
grep -E "^v${series}\.[0-9]+\.[0-9]+$" "$TAGS_FILE" |
|
||||
sed 's/^v//' |
|
||||
sort -t . -k1,1n -k2,2n -k3,3n |
|
||||
tail -n 1 |
|
||||
sed 's/^/v/'
|
||||
}
|
||||
|
||||
# checkout_runner <git ref>, builds the runner binary at $BIN
|
||||
checkout_runner() {
|
||||
local ref="$1"
|
||||
|
||||
if [ -d "$SRC_DIR/.git" ]; then
|
||||
git -C "$SRC_DIR" remote set-url origin "$RUNNER_REMOTE"
|
||||
else
|
||||
rm -rf "$SRC_DIR"
|
||||
git init --quiet "$SRC_DIR"
|
||||
git -C "$SRC_DIR" remote add origin "$RUNNER_REMOTE"
|
||||
fi
|
||||
git -C "$SRC_DIR" fetch --quiet --depth 1 origin "$ref"
|
||||
git -C "$SRC_DIR" checkout --quiet --detach FETCH_HEAD
|
||||
|
||||
(cd "$SRC_DIR" && go build -o "$BIN" .)
|
||||
}
|
||||
|
||||
# the commands the reference documents, in the order they are presented
|
||||
COMMANDS=(register daemon exec cache-server generate-config bug-report)
|
||||
|
||||
# one short paragraph per command, printed above its help output
|
||||
describe_command() {
|
||||
case "$1" in
|
||||
register)
|
||||
echo 'Registers the runner against a Gitea instance and writes the registration file. Interactive unless `--no-interactive` is given; the token can also come from `--token-file` or the `GITEA_RUNNER_REGISTRATION_TOKEN` environment variable. See [Registering a runner](../registration.md).'
|
||||
;;
|
||||
daemon)
|
||||
echo 'Runs the runner: it polls the instance for jobs and executes them until it is stopped. `--labels` (default: `GITEA_RUNNER_LABELS`) overrides the labels of an already registered runner, and `--once` exits after a single job.'
|
||||
;;
|
||||
exec)
|
||||
echo 'Runs a workflow from the current repository locally, without a Gitea instance and without the runner configuration file. Useful for debugging a workflow before pushing it. Runner YAML is not loaded, so hooks and cache settings do not apply.'
|
||||
;;
|
||||
cache-server)
|
||||
echo 'Runs only the cache server, so several runners can share one cache. `--dir`, `--host` and `--port` override the matching `cache.*` keys; every other setting, `cache.external_secret` included, has to come from the config file. See [Caching](../cache.md#sharing-a-cache-between-runners).'
|
||||
;;
|
||||
generate-config)
|
||||
echo 'Prints the commented example configuration on stdout, which is the starting point for a config file: `gitea-runner generate-config > config.yaml`.'
|
||||
;;
|
||||
bug-report)
|
||||
echo 'Prints the runner version, Go version, OS/architecture and CPU count, for pasting into an issue.'
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
# generate_reference <git ref> <target directory>
|
||||
generate_reference() {
|
||||
local ref="$1" target="$2" cmd
|
||||
|
||||
mkdir -p "$target"
|
||||
checkout_runner "$ref"
|
||||
|
||||
{
|
||||
cat <<'EOF'
|
||||
---
|
||||
sidebar_position: 1
|
||||
description: Every gitea-runner command and flag, generated from the runner sources.
|
||||
---
|
||||
|
||||
# Command line reference
|
||||
|
||||
{/* Generated by update_runner_docs.sh from the gitea/runner sources, do not edit. */}
|
||||
|
||||
`gitea-runner` is a single binary with one subcommand per task. `--config` / `-c` is
|
||||
global: every command that reads configuration accepts it, and commands that do not
|
||||
read any ignore it.
|
||||
|
||||
EOF
|
||||
printf '## gitea-runner\n\n```text\n'
|
||||
"$BIN" --help
|
||||
printf '```\n'
|
||||
|
||||
for cmd in "${COMMANDS[@]}"; do
|
||||
printf '\n## %s\n\n' "$cmd"
|
||||
describe_command "$cmd"
|
||||
printf '\n```text\n'
|
||||
"$BIN" "$cmd" --help
|
||||
printf '```\n'
|
||||
done
|
||||
} > "$target/cli.md"
|
||||
|
||||
{
|
||||
cat <<'EOF'
|
||||
---
|
||||
sidebar_position: 2
|
||||
description: The commented example configuration of the runner, generated from the runner sources.
|
||||
---
|
||||
|
||||
# Example configuration
|
||||
|
||||
{/* Generated by update_runner_docs.sh from the gitea/runner sources, do not edit. */}
|
||||
|
||||
This is the output of `gitea-runner generate-config`. It is safe to use unmodified,
|
||||
and it is the authoritative list of every option the runner understands. See
|
||||
[Configuration](../configuration.md) for what the options mean and how the file is
|
||||
loaded.
|
||||
|
||||
```yaml
|
||||
EOF
|
||||
"$BIN" generate-config
|
||||
printf '```\n'
|
||||
} > "$target/config-example.md"
|
||||
|
||||
echo "wrote $target/cli.md and $target/config-example.md from $RUNNER_REMOTE@$ref"
|
||||
}
|
||||
|
||||
# regenerates every documented release series from its newest stable tag
|
||||
generate_released() {
|
||||
local dir series tag found=0
|
||||
|
||||
for dir in "$VERSIONED_DOCS"/version-*/reference; do
|
||||
[ -d "$dir" ] || continue
|
||||
found=1
|
||||
series="${dir#"$VERSIONED_DOCS"/version-}"
|
||||
series="${series%/reference}"
|
||||
|
||||
tag="$(latest_stable_tag "$series")"
|
||||
if [ -z "$tag" ]; then
|
||||
echo "no stable v$series tag in $RUNNER_API, skipping $dir" >&2
|
||||
continue
|
||||
fi
|
||||
generate_reference "$tag" "$dir"
|
||||
done
|
||||
|
||||
if [ "$found" -eq 0 ]; then
|
||||
echo "no $VERSIONED_DOCS/version-*/reference directory to regenerate" >&2
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
case "${1:-}" in
|
||||
--released)
|
||||
generate_released
|
||||
;;
|
||||
-h | --help)
|
||||
sed -n '3,17s/^#\{1,2\} \{0,1\}//p' "$0"
|
||||
;;
|
||||
*)
|
||||
generate_reference "${1:-main}" "${2:-runner-docs/reference}"
|
||||
;;
|
||||
esac
|
||||
Reference in New Issue
Block a user