oblachno-oss/grm
3
0
Fork 0
Code Issues 20 Pull Requests Actions Packages Projects Releases 14 Wiki Activity

GRM-43: docs: fix broken wiki links and add missing token setup steps

Browse Source
This commit is contained in:
emil
2026-06-21 22:13:50 +00:00
parent a0e6cd0a73
commit 7dfc9f6014
6 changed files with 93 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.env.example
+6 -3
View File
@@ -1,11 +1,14 @@
# Gitea instance URL (used for runner registration and API validation)
GITEA_URL=https://git.example.com
# Runner registration token from Gitea admin panel:
# Admin → Actions → Runners → Create Registration Token
# Runner registration token from Gitea.
# Three levels are available:
# Instance-level: Site Administration → Actions → Runners → Create Registration Token
# Org-level: Organization → Settings → Actions → Runners → Create Registration Token
# Repo-level: Repository → Settings → Actions → Runners → Create Registration Token
GITEA_REGISTRATION_TOKEN=your-registration-token
# Gitea API token for optional post-install API checks (informational only).
# Gitea admin API token for optional post-install API checks (informational only).
# The integration test primarily verifies the runner by checking:
# 1. The .runner registration file exists and is valid
# 2. The container/service is running
README.md
+10 -8
View File
@@ -15,30 +15,32 @@ Each runner runs in an isolated **rootless Docker** environment under a dedicate
git clone https://git.oblachno.oblachno.fyi/oblachno-oss/grm.git
cd grm
make setup
cp .env.example .env # Edit with your Gitea URL and registration token
cp .env.example .env # Edit with your Gitea URL and tokens
grm install 192.168.1.10 --user ubuntu --key ~/.ssh/id_ed25519 --name prod-runner
```
> **Tokens:** You need two tokens from your Gitea instance — a **registration token** to register runners, and an **admin API token** for optional post-install verification. See [Getting Started](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/Getting-Started.-) for detailed setup instructions.
## Documentation
Full documentation lives on the [**GRM Wiki**](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki).
### User Documentation
- [Getting Started](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/Getting-Started) — Installation, quick start, first run
- [Getting Started](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/Getting-Started.-) — Installation, quick start, token setup, first run
- [Installation](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/Installation) — Prerequisites, setup, multiple instances
- [CLI Commands](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/CLI-Commands) — All commands with arguments and options
- [CLI Commands](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/CLI-Commands.-) — All commands with arguments and options
- [Troubleshooting](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/Troubleshooting) — Common issues and solutions
- [FAQ](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/FAQ) — Frequently asked questions
### Technical Documentation
- [Architecture](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/Architecture) — High-level design, component interactions
- [Development Setup](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/Development-Setup) — Environment setup, dependencies, local testing
- [CI/CD Workflow](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/CI-CD-Workflow) — How CI works, release process, branch protection
- [Testing Strategy](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/Testing-Strategy) — Unit, integration, and Molecule tests
- [Decision Log](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/Decision-Log) — Key technical decisions and rationale
- [Contributing Guide](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/Contributing-Guide) — Coding standards, PR workflow, commit rules
- [Development Setup](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/Development-Setup.-) — Environment setup, dependencies, local testing
- [CI/CD Workflow](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/CI-CD-Workflow.-) — How CI works, release process, branch protection
- [Testing Strategy](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/Testing-Strategy.-) — Unit, integration, and Molecule tests
- [Decision Log](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/Decision-Log.-) — Key technical decisions and rationale
- [Contributing Guide](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/Contributing-Guide.-) — Coding standards, PR workflow, commit rules
## License
docs/user/faq.md
+15 -1
View File
@@ -2,7 +2,21 @@
### How do I obtain the Gitea registration token?
The runner registration token is obtained from your Gitea instance: **Admin → Actions → Runners → Create Registration Token**. Set it as `GITEA_REGISTRATION_TOKEN` in your `.env` file or pass it via `--token` on the command line.
There are three levels of registration tokens, depending on which repositories the runner should serve:
- **Instance-level** — Site Administration → Actions → Runners → Create Registration Token. The runner will handle jobs from all repositories.
- **Organization-level** — Organization → Settings → Actions → Runners → Create Registration Token. The runner will only handle jobs from repositories in that organization.
- **Repository-level** — Repository → Settings → Actions → Runners → Create Registration Token. The runner will only handle jobs from that specific repository.
Set the token as `GITEA_REGISTRATION_TOKEN` in your `.env` file or pass it via `--token` on the command line.
### What is the REPO_TOKEN and do I need it?
`REPO_TOKEN` is a Gitea admin API token used for optional post-install verification. When set, GRM queries the Gitea API after installation to confirm the runner appears in the runner list. This is purely informational — the integration test passes/fails based on the `.runner` file and systemd service, not the API check.
To generate one: Settings → Applications → Generate New Token, with the `admin` scope (or at minimum `read:user`, `read:repository`, `read:admin`).
If you skip it, GRM will still verify the runner correctly — it just won't show the extra API confirmation.
### How do I skip the sudo password prompt for automation?
docs/user/getting-started.md
+59 -13
View File
@@ -3,8 +3,8 @@
## Developer Setup
```bash
git clone https://git.oblachno.oblachno.com/oblachno/gitea-runner-manager.git
cd gitea-runner-manager
git clone https://git.oblachno.oblachno.fyi/oblachno-oss/grm.git
cd grm
pyenv install 3.12
pyenv local 3.12
make setup
@@ -12,23 +12,69 @@ make setup
## Configure Gitea Credentials
```bash
cp .env.example .env
# Edit .env:
# GITEA_URL=https://git.example.com
# GITEA_REGISTRATION_TOKEN=your-registration-token
```
GRM needs two tokens from your Gitea instance: a **registration token** (required) and an **admin API token** (optional, for post-install verification).
`GITEA_REGISTRATION_TOKEN` is the runner registration token obtained from your Gitea instance (Admin → Actions → Runners → Create Registration Token).
### Step 1: Get the Registration Token
### Admin API Token (optional)
The registration token tells Gitea to accept the runner when it connects.
Set `GITEA_ADMIN_TOKEN` to enable informational API checks during integration test. This is **optional** — the test primarily verifies the runner by checking:
1. Log in to your Gitea instance as an administrator
2. Navigate to **Site Administration → Actions → Runners**
3. Click **Create Registration Token**
4. Copy the token — it starts with `GR`
> **Note:** There are three levels of registration tokens:
> - **Instance-level** (Site Administration → Actions → Runners) — registers a runner for all repositories
> - **Organization-level** (Organization → Settings → Actions → Runners) — registers a runner for repos in that organization
> - **Repository-level** (Repository → Settings → Actions → Runners) — registers a runner for a single repository
>
> Use instance-level tokens for shared runners, and repo-level tokens for dedicated runners.
### Step 2: Get the Admin API Token (optional)
The admin API token enables post-install API checks that verify the runner appears in Gitea's runner list. This is purely informational — the integration test primarily verifies the runner by checking:
1. **`.runner` registration file** exists and contains valid JSON (proves successful registration)
2. **Systemd user service** is active (proves daemon is polling for jobs)
API checks, if enabled, are purely informational and do not affect pass/fail.
To get an admin API token:
1. Go to **Settings → Applications → Generate New Token**
2. Give it a name (e.g., "GRM Install Verification")
3. Select the **admin** scope (or at minimum: `read:user`, `read:repository`, `read:admin`)
4. Click **Generate Token** and copy it immediately (it won't be shown again)
### Step 3: Create the `.env` File
```bash
cp .env.example .env
```
Edit `.env` with your tokens:
```bash
# Your Gitea instance URL
GITEA_URL=https://git.example.com
# Registration token from Step 1
GITEA_REGISTRATION_TOKEN=GRxxxxxxxxxxxxxxxxxx
# Admin API token from Step 2 (optional)
REPO_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
### Environment Variables Reference
| Variable | Required | Description |
|----------|----------|-------------|
| `GITEA_URL` | Yes | Gitea instance URL (e.g., `https://git.example.com`) |
| `GITEA_REGISTRATION_TOKEN` | Yes | Runner registration token from Gitea admin panel |
| `REPO_TOKEN` | No | Admin API token for post-install verification |
| `GITEA_INTEGRATION_RETRIES` | No | API check retries (default: 3) |
| `GITEA_RUNNER_USER` | No | Default SSH user (overrides `--user`) |
| `GITEA_RUNNER_KEY` | No | Default SSH key path (overrides `--key`) |
| `GITEA_RUNNER_LABELS` | No | Default runner labels (overrides `--labels`) |
| `GRM_LANG` | No | UI language: `en`, `bg`, `de`, `ru`, `zh` (default: `en`) |
## Install a Runner
@@ -55,7 +101,7 @@ The installer performs an automated integration test that verifies:
You can also check the Gitea UI under **Actions → Runners** to confirm the runner appears as **Online**.
Optional: If `GITEA_ADMIN_TOKEN` is set, the installer will also query the Gitea API and report whether the runner appears in the admin or repo runners list. This is purely informational.
Optional: If `REPO_TOKEN` is set, the installer will also query the Gitea API and report whether the runner appears in the admin or repo runners list. This is purely informational.
## View Logs
docs/user/installation.md
+1
View File
@@ -4,6 +4,7 @@
- **SSH key authentication** — The remote host must be reachable via SSH using the user specified with `--user` and the private key specified with `--key`. GRM uses Ansible under the hood, which connects to the target host over SSH to execute all installation and configuration tasks. Without valid SSH credentials, Ansible cannot establish a connection and the deployment will fail.
- **Sudo access** — GRM requires root privileges on the remote host to create system users, install packages, and configure rootless Docker. By default, you will be prompted interactively for the sudo password. For automation or uninterrupted workflows, configure passwordless sudo on the remote host and pass `--no-ask-become-pass`.
- **Gitea registration token** — You need a runner registration token from your Gitea instance. See [Getting Started](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/Getting-Started.-) for detailed instructions on obtaining tokens.
## Supported Operating Systems
docs/user/troubleshooting.md
+2
View File
@@ -7,6 +7,7 @@ This is a harmless cleanup traceback from Molecule's Docker driver when the test
## Runner appears offline after installation
- Check that the `GITEA_URL` and `GITEA_REGISTRATION_TOKEN` environment variables are correct.
- Verify the registration token has not expired — generate a new one from Gitea if needed (Site Administration → Actions → Runners → Create Registration Token).
- Verify the runner service is running: `sudo -u grm-<name> systemctl --user status gitea-runner`.
- Check logs for registration errors.
@@ -16,6 +17,7 @@ The test checks two things:
1. **`.runner` file missing or invalid** — Registration failed. Check:
- `GITEA_URL` and `GITEA_REGISTRATION_TOKEN` are correct
- The registration token is valid and has not expired
- Runner logs for registration errors
- The `.runner` file should exist at `/var/lib/gitea-runner/<name>/.runner`