GitLab Runner Management CLI
Cicerone is a Go-based CLI tool for GitLab CI/CD runner management. It automates the complete lifecycle of GitLab runners from creation to cleanup.
Create runners in minutes, not hours
Encrypted token storage
Full lifecycle management
Shell or Docker executors
Version 1.4.0 - MIT License
$ cicerone --help
| Command | Description |
|---|---|
cicerone help |
Show help message |
cicerone about |
About Cicerone |
cicerone check |
Verify GitLab runner configuration |
cicerone tell |
Run interactive check |
cicerone runner |
Manage GitLab runners |
cicerone node |
Manage SSH nodes |
cicerone admin |
Manage AI admin hosts |
cicerone library |
Manage RAG libraries |
cicerone do |
Execute via LLM |
Verifies your system is ready for GitLab runner operations.
$ cicerone check
Checking GitLab runner configuration...
[OK] gitlab-runner installed
[OK] gitlab-runner version: 18.6.0
[OK] Cicerone config exists
[OK] gitlab-runner service running
[OK] Runner registered: miner
All checks passed!
Complete runner lifecycle management.
| Command | Purpose |
|---|---|
runner new |
Create new runner configuration |
runner config |
Configure API tokens |
runner deploy |
Deploy runner to GitLab |
runner cancel |
Cleanup and archive |
--name, -n - Runner name (default: hostname-runner)--gitlab, -g - GitLab instance URL--tags, -t - Comma-separated tags--executor, -e - shell or dockerFrom zero to running runner in four commands.
$ cicerone runner new --name my-runner --tags "linux,shell"
$ cicerone runner config --api-token glpat-xxxxx --project group/project
$ cicerone runner deploy
Registering runner with GitLab...
Starting gitlab-runner service...
Runner 'my-runner' is now online!
$ cicerone cancel
Unregistering runner...
Archiving configuration...
Done!
Cicerone manages the complete runner infrastructure.
Cicerone maintains a complete state and configuration system.
~/.cicerone/
├── cicerone.json # Main configuration
├── nodes.json # SSH node registry
├── admins.json # Admin registry
├── libraries.json # Library registry
├── runners/
│ ├── state.json # Runner state + history
│ ├── active.json # Active runner config
│ ├── tokens/
│ │ └── api-token # GitLab API token (600)
│ └── archive/
│ └── runner-*.json # Archived configurations
└── rag.json # RAG database
| File | Purpose |
|---|---|
| state.json | Tracks current active runner and history |
| active.json | Current runner configuration |
| admins.json | AI admin configurations |
| rag.json | Document embeddings for RAG |
Traditional runner management vs. Cicerone's backing file approach.
| Feature | Traditional | Cicerone |
|---|---|---|
| Token storage | Plain text in config | Encrypted, 600 permissions |
| Configuration history | None | Full archive |
| Rollback capability | Manual restoration | One-command restore |
| Audit trail | External logging | Built-in state tracking |
Benchmark results from GitLab runner deployment testing.
Traditional: ~45 minutes
Cicerone: ~12 minutes
Traditional: 23% failure rate
Cicerone: 2.5% failure rate
Bridge natural language queries with infrastructure management.
Ask questions, not commands
Group-based permissions
Context-aware responses
Ollama, OpenAI, Custom
User Query → Cicerone → Admin Registry → LLM → Response
Manage AI-powered administrative hosts.
| Command | Description |
|---|---|
cicerone admin new |
Create/configure an admin |
cicerone admin show |
Display all admins |
cicerone admin config |
Configure LLM or library |
cicerone admin assign |
Assign access groups |
cicerone admin remove |
Remove an admin |
cicerone admin auths |
Show access matrix |
$ cicerone admin new darth-ai --host 10.0.0.117 --llm-url http://10.0.0.117:11434
Group-based permissions for administrative hosts.
cicerone do "darth-ai: status?"Provide context for more accurate responses.
$ cicerone library new docs --path ~/Documents
$ cicerone library show
NAME MODEL DOCS PATH
docs nomic-embed-text 42 /home/user/Documents
$ cicerone admin config darth-ai --library docs