394 lines
12 KiB
Markdown
394 lines
12 KiB
Markdown
# CLI Commands
|
|
|
|
GRM provides the following CLI commands for managing Gitea Actions runners. The base command is `grm`.
|
|
|
|
## Command Summary
|
|
|
|
| Command | Arguments | Description |
|
|
|---------|-----------|-------------|
|
|
| `grm install` | `<host>` | Install and configure a runner on a remote host |
|
|
| `grm update` | `<host>` | Update the gitea_runner binary on a remote host |
|
|
| `grm start` | `<runner_name>` | Start a registered runner |
|
|
| `grm stop` | `<runner_name>` | Stop a registered runner |
|
|
| `grm restart` | `<runner_name>` | Restart a runner (stop, prune Docker images, start) |
|
|
| `grm enable` | `<runner_name>` | Enable a runner to start on boot |
|
|
| `grm disable` | `<runner_name>` | Disable and deregister a runner |
|
|
| `grm status` | `<runner_name>` | Check the status of a registered runner |
|
|
| `grm remove` | `<runner_name>` | Remove a runner entirely |
|
|
| `grm list` | — | List all registered runners with live status |
|
|
| `grm health` | `[runner_name]` | Run health check (Docker, runner service, disk) on one or all runners |
|
|
| `grm trigger-workflow` | `<workflow_id>` | Trigger a Gitea Actions workflow via the API |
|
|
| `grm --version` | — | Show the installed version |
|
|
|
|
### Common lifecycle options
|
|
|
|
The `start`, `stop`, `enable`, `status`, `disable`, and `remove` commands all accept these override options. By default, connection details are read from the local registry (`~/.local/share/grm/runners.json`).
|
|
|
|
| Option | Short | Description |
|
|
|--------|-------|-------------|
|
|
| `--host` | — | Override host from registry |
|
|
| `--user` | `-u` | Override user from registry |
|
|
| `--key` | `-k` | Override SSH key from registry |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | Prompt for sudo password (default) or skip it |
|
|
|
|
## install
|
|
|
|
Install and configure a Gitea Runner on a remote host.
|
|
|
|
```bash
|
|
grm install <host> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `host` | Remote host (IP address or hostname) |
|
|
|
|
**Options:**
|
|
|
|
| Option | Short | Default | Description |
|
|
|--------|-------|---------|-------------|
|
|
| `--user` | `-u` | `GITEA_RUNNER_USER` env or current login | SSH user |
|
|
| `--key` | `-k` | `GITEA_RUNNER_KEY` env | Path to SSH private key |
|
|
| `--name` | `-n` | hostname | Gitea Runner name |
|
|
| `--token` | `-t` | `GITEA_REGISTRATION_TOKEN` env | Registration token |
|
|
| `--url` | — | `GITEA_URL` env | Gitea URL |
|
|
| `--admin-token` | `-a` | `CI_GITEA_TOKEN` env | Gitea admin API token for integration test |
|
|
| `--integration-retries` | `-r` | `3` (`GITEA_INTEGRATION_RETRIES` env) | Integration test API retries |
|
|
| `--labels` | `-l` | `GITEA_RUNNER_LABELS` env | Runner labels for Gitea Actions. Example: `docker:docker://alpine:latest` |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | `--ask-become-pass` | Prompt for sudo password (default) or skip it |
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
grm install 192.168.1.10 --user ubuntu --key ~/.ssh/id_ed25519 --name prod-runner
|
|
```
|
|
|
|
## update
|
|
|
|
Update the Gitea Runner binary on a remote host.
|
|
|
|
```bash
|
|
grm update <host> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `host` | Remote host (IP address or hostname) |
|
|
|
|
**Options:**
|
|
|
|
| Option | Short | Default | Description |
|
|
|--------|-------|---------|-------------|
|
|
| `--user` | `-u` | `GITEA_RUNNER_USER` env or current login | SSH user |
|
|
| `--key` | `-k` | `GITEA_RUNNER_KEY` env | Path to SSH private key |
|
|
| `--version` | `-v` | — | Specific Gitea Runner version |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | `--ask-become-pass` | Prompt for sudo password (default) or skip it |
|
|
|
|
## start
|
|
|
|
Start a registered Gitea Runner.
|
|
|
|
```bash
|
|
grm start <runner_name> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `runner_name` | Name of the registered runner |
|
|
|
|
**Options (common lifecycle options):**
|
|
|
|
| Option | Short | Description |
|
|
|--------|-------|-------------|
|
|
| `--host` | — | Override host from registry |
|
|
| `--user` | `-u` | Override user from registry |
|
|
| `--key` | `-k` | Override SSH key from registry |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | Prompt for sudo password (default) or skip it |
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
grm start prod-runner
|
|
# Override stored values:
|
|
grm start prod-runner --host 192.168.1.11 --user root
|
|
```
|
|
|
|
## stop
|
|
|
|
Stop a registered Gitea Runner.
|
|
|
|
```bash
|
|
grm stop <runner_name> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `runner_name` | Name of the registered runner |
|
|
|
|
**Options (common lifecycle options):**
|
|
|
|
| Option | Short | Description |
|
|
|--------|-------|-------------|
|
|
| `--host` | — | Override host from registry |
|
|
| `--user` | `-u` | Override user from registry |
|
|
| `--key` | `-k` | Override SSH key from registry |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | Prompt for sudo password (default) or skip it |
|
|
|
|
## restart
|
|
|
|
Restart a registered Gitea Runner (stop, prune Docker images, start).
|
|
|
|
```bash
|
|
grm restart <runner_name> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `runner_name` | Name of the registered runner |
|
|
|
|
**Options (common lifecycle options):**
|
|
|
|
| Option | Short | Description |
|
|
|--------|-------|-------------|
|
|
| `--host` | — | Override host from registry |
|
|
| `--user` | `-u` | Override user from registry |
|
|
| `--key` | `-k` | Override SSH key from registry |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | Prompt for sudo password (default) or skip it |
|
|
|
|
## enable
|
|
|
|
Enable a registered Gitea Runner to start on boot.
|
|
|
|
```bash
|
|
grm enable <runner_name> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `runner_name` | Name of the registered runner |
|
|
|
|
**Options (common lifecycle options):**
|
|
|
|
| Option | Short | Description |
|
|
|--------|-------|-------------|
|
|
| `--host` | — | Override host from registry |
|
|
| `--user` | `-u` | Override user from registry |
|
|
| `--key` | `-k` | Override SSH key from registry |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | Prompt for sudo password (default) or skip it |
|
|
|
|
## disable
|
|
|
|
Disable a registered Gitea Runner and deregister it.
|
|
|
|
```bash
|
|
grm disable <runner_name> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `runner_name` | Name of the registered runner |
|
|
|
|
**Options:**
|
|
|
|
| Option | Short | Default | Description |
|
|
|--------|-------|---------|-------------|
|
|
| `--host` | — | from registry | Override host from registry |
|
|
| `--user` | `-u` | from registry | Override user from registry |
|
|
| `--key` | `-k` | from registry | Override SSH key from registry |
|
|
| `--token` | `-t` | `GITEA_REGISTRATION_TOKEN` env | Registration token |
|
|
| `--url` | — | `GITEA_URL` env | Gitea URL |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | `--ask-become-pass` | Prompt for sudo password (default) or skip it |
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
grm disable prod-runner --token <token>
|
|
```
|
|
|
|
## status
|
|
|
|
Check the status of a registered Gitea Runner.
|
|
|
|
```bash
|
|
grm status <runner_name> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `runner_name` | Name of the registered runner |
|
|
|
|
**Options (common lifecycle options):**
|
|
|
|
| Option | Short | Description |
|
|
|--------|-------|-------------|
|
|
| `--host` | — | Override host from registry |
|
|
| `--user` | `-u` | Override user from registry |
|
|
| `--key` | `-k` | Override SSH key from registry |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | Prompt for sudo password (default) or skip it |
|
|
|
|
## remove
|
|
|
|
Remove a registered Gitea Runner entirely.
|
|
|
|
```bash
|
|
grm remove <runner_name> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `runner_name` | Name of the registered runner |
|
|
|
|
**Options:**
|
|
|
|
| Option | Short | Default | Description |
|
|
|--------|-------|---------|-------------|
|
|
| `--host` | — | from registry | Override host from registry |
|
|
| `--user` | `-u` | from registry | Override user from registry |
|
|
| `--key` | `-k` | from registry | Override SSH key from registry |
|
|
| `--token` | `-t` | `GITEA_REGISTRATION_TOKEN` env | Registration token |
|
|
| `--url` | — | `GITEA_URL` env | Gitea URL |
|
|
| `--force` | `-f` | — | Skip remote cleanup and only remove the local registry entry |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | `--ask-become-pass` | Prompt for sudo password (default) or skip it |
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
grm remove prod-runner --token <token>
|
|
```
|
|
|
|
## list
|
|
|
|
List all registered runners with live status.
|
|
|
|
```bash
|
|
grm list
|
|
```
|
|
|
|
This command takes no arguments or options. It displays a table with columns: NAME, HOST, USER, LABELS, STATUS for all runners stored in the local registry at `~/.local/share/grm/runners.json`.
|
|
|
|
The status is checked live by running an Ansible ad-hoc command on each remote host (`systemctl --user is-active gitea-runner`). Possible status values: `active`, `inactive`, `failed`, `unknown`.
|
|
|
|
**Example output:**
|
|
|
|
```text
|
|
NAME HOST USER LABELS STATUS
|
|
------------------------------------------------------------------------------------------
|
|
prod-runner 192.168.1.10 ubuntu docker:docker://gitea/... active
|
|
build-runner 192.168.1.10 ubuntu docker:docker://gitea/... active
|
|
test-runner 192.168.1.20 ubuntu inactive
|
|
```
|
|
|
|
If no runners are registered:
|
|
|
|
```text
|
|
No runners registered. Use 'grm install' to add one.
|
|
```
|
|
|
|
## health
|
|
|
|
Run a health check on one or all registered runners. Checks Docker daemon status, Gitea runner service status, and disk space usage. Unhealthy services are automatically restarted by the healthcheck script.
|
|
|
|
```bash
|
|
grm health [runner_name] [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `runner_name` | (optional) Name of the runner to check. If omitted, checks all registered runners. |
|
|
|
|
**Options (common lifecycle options):**
|
|
|
|
| Option | Short | Description |
|
|
|--------|-------|-------------|
|
|
| `--host` | — | Override host from registry |
|
|
| `--user` | `-u` | Override user from registry |
|
|
| `--key` | `-k` | Override SSH key from registry |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | Prompt for sudo password (default) or skip it |
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
grm health
|
|
# Check a specific runner:
|
|
grm health prod-runner
|
|
```
|
|
|
|
Output shows NAME, HOST, HEALTHY (yes/no), and MESSAGE columns. The command exits with code 1 if any runner is unhealthy.
|
|
|
|
The health check is also run automatically via a systemd timer installed by the Ansible role. See `ansible/roles/gitea_runner/templates/runner-healthcheck.sh.j2` for the script and `runner-healthcheck.timer.j2` for the timer.
|
|
|
|
## trigger-workflow
|
|
|
|
Trigger a Gitea Actions workflow via the API.
|
|
|
|
```bash
|
|
grm trigger-workflow <workflow_id> [options]
|
|
grm trigger-workflow --list
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `workflow_id` | Workflow filename (e.g., `ci.yml`) or ID |
|
|
|
|
**Options:**
|
|
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| `--list` | List available workflows in the repository |
|
|
| `--ref` | Branch or tag to trigger on (default: repository default branch) |
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
grm trigger-workflow --list
|
|
grm trigger-workflow ci.yml --ref master
|
|
```
|
|
|
|
## --version
|
|
|
|
Show the installed GRM version.
|
|
|
|
```bash
|
|
grm --version
|
|
```
|
|
|
|
This reports the version from `__version__` in `src/grm/__init__.py`, which is the single source of truth set by the automated release pipeline.
|
|
|
|
## Environment Variables
|
|
|
|
All CLI options can be set via environment variables (loaded from `.env` via python-dotenv). Command-line flags take precedence over environment variables.
|
|
|
|
| Variable | Used by | Description |
|
|
|----------|---------|-------------|
|
|
| `GITEA_URL` | `install`, `disable`, `remove` | Gitea instance URL |
|
|
| `GITEA_REGISTRATION_TOKEN` | `install`, `disable`, `remove` | Runner registration token |
|
|
| `CI_GITEA_TOKEN` | `install` | Admin API token for integration test |
|
|
| `GITEA_INTEGRATION_RETRIES` | `install` | API check retries (default: 3) |
|
|
| `GITEA_RUNNER_USER` | `install`, `update` | Default SSH user |
|
|
| `GITEA_RUNNER_KEY` | `install`, `update` | Default SSH key path |
|
|
| `GITEA_RUNNER_LABELS` | `install` | Default runner labels |
|
|
| `GRM_LANG` | all | UI language: `en`, `bg`, `de`, `ru`, `zh`, `pl` |
|
|
| `GRM_LOG_LEVEL` | all | Console log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
|