oblachno-oss/grm
3
0
Fork 0
Code Issues 31 Pull Requests 1 Actions Packages Projects Releases 18 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
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