add documentation and cheatsheet

2026-01-18 18:06:34 +01:00
parent 42de568eae
commit c8b85e8977
2 changed files with 538 additions and 0 deletions
--- a/CHEATSHEET.md
+++ b/CHEATSHEET.md
@@ -0,0 +1,153 @@
+# gitea-ci Cheatsheet
+
+## Quick Reference
+
+```
+┌────────────────────────────────────────────────────────────────────────────┐
+│ SETUP
+├────────────────────────────────────────────────────────────────────────────┤
+│ export GITEA_URL="https://gitea.example.com"
+│ export GITEA_TOKEN="your-token"
+│ gitea-ci config --test                     Verify connectivity
+└────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Common Tasks
+
+```
+┌──────────────────────────┬─────────────────────────────────────────────────┐
+│ Task                     │ Command
+├──────────────────────────┼─────────────────────────────────────────────────┤
+│ List runs                │ gitea-ci list owner/repo
+│ List failed only         │ gitea-ci list --failed
+│ Show run status          │ gitea-ci status owner/repo 123
+│ View logs                │ gitea-ci logs -R 123
+│ Watch live               │ gitea-ci watch owner/repo
+│ Trigger workflow         │ gitea-ci trigger -w deploy.yml
+│ Re-run failed            │ gitea-ci rerun -R 123 -f
+│ Cancel run               │ gitea-ci cancel -R 123
+│ Validate workflows       │ gitea-ci validate
+└──────────────────────────┴─────────────────────────────────────────────────┘
+```
+
+## Commands at a Glance
+
+```
+┌─────────────────┬────────┬──────────────────────────────────────────────────┐
+│ Command         │ Alias  │ Purpose
+├─────────────────┼────────┼──────────────────────────────────────────────────┤
+│ list            │ ls l   │ List workflow runs
+│ status          │ s      │ Show run details
+│ logs            │ log    │ View job logs
+│ watch           │ w      │ Live watch runs
+│ stats           │        │ Statistics with graphs
+│ trigger         │ t      │ Trigger workflow_dispatch
+│ rerun           │        │ Re-run workflow/jobs
+│ cancel          │        │ Cancel running workflow
+│ delete          │ rm     │ Delete workflow run
+│ artifacts       │ art    │ List/download artifacts
+│ pr              │        │ PR CI status
+│ compare         │ diff   │ Compare two runs
+│ workflows       │ wf     │ List workflow files
+│ validate        │ lint   │ Validate local workflows
+│ runners         │        │ Manage runners
+│ register-token  │ regtoken│ Get registration token
+│ config          │        │ Configure tool
+│ repo            │        │ Repository operations
+│ infra           │        │ Infrastructure status
+└─────────────────┴────────┴──────────────────────────────────────────────────┘
+```
+
+## Flags
+
+```
+┌────────────────────────┬────────────────────────────────────────────────────┐
+│ Flag                   │ Meaning
+├────────────────────────┼────────────────────────────────────────────────────┤
+│ -o, --owner            │ Repository owner
+│ -r, --repo             │ Repository name
+│ -R, --run              │ Run ID
+│ -j, --job              │ Job ID
+│ -n, --limit            │ Number of items
+│ -b, --branch           │ Branch filter
+│ -w, --workflow         │ Workflow file
+│ -i, --input            │ Workflow input (key=value)
+│ -f, --force            │ Skip confirmation
+│ --json                 │ JSON output
+│ --compact              │ Single-line output
+└────────────────────────┴────────────────────────────────────────────────────┘
+```
+
+## Status Symbols
+
+```
+✓  success       ●  running       ◌  queued
+✗  failure       ○  pending       ⊘  cancelled/skipped
+```
+
+## Patterns
+
+### After git push
+
+```sh
+git push && gitea-ci watch --notify
+```
+
+### Check last run status
+
+```sh
+gitea-ci list --compact | head -1
+```
+
+### Re-run latest failed
+
+```sh
+gitea-ci rerun -R "$(gitea-ci list --failed --compact | head -1 | awk '{print $1}')" -f
+```
+
+### Validate before commit
+
+```sh
+gitea-ci validate --strict && git commit -m "message"
+```
+
+### Export run data
+
+```sh
+gitea-ci list --json > runs.json
+gitea-ci status -R 123 --json | jq '.jobs[].name'
+```
+
+### Watch with timeout
+
+```sh
+gitea-ci watch -t 600 --notify  # 10 min timeout
+```
+
+### Get artifact
+
+```sh
+gitea-ci artifacts -R 123
+gitea-ci artifacts -d 456 -O build.zip
+```
+
+## Environment
+
+```
+GITEA_URL      Gitea instance URL
+GITEA_TOKEN    API authentication token
+NO_COLOR       Disable colors when set
+```
+
+## Config File
+
+`~/.config/gitea-ci/config.json`
+
+```json
+{
+  "url": "https://gitea.example.com",
+  "token": "...",
+  "default_owner": "myorg",
+  "default_repo": "myproject"
+}
+```