# gitea-ci Command-line tool for monitoring and managing Gitea Actions workflows. ## Features - List workflow runs across repositories - Show detailed job status with live updates - Stream build logs in real-time - Trigger workflows manually (workflow_dispatch) - Re-run failed jobs, cancel running workflows - List and download build artifacts - View PR check status - Compare workflow runs - Manage runners - Validate workflow files locally - Desktop notifications on completion - JSON output for scripting ## Installation ```sh # Clone the repository git clone https://github.com/user/gitea-ci.git cd gitea-ci # Option 1: Symlink the wrapper script ln -s "$(pwd)/gitea-ci.py" ~/.local/bin/gitea-ci # Option 2: Copy files (wrapper + src/ + style.py) cp -r gitea-ci.py style.py src/ ~/.local/bin/gitea-ci/ ln -s ~/.local/bin/gitea-ci/gitea-ci.py ~/.local/bin/gitea-ci ``` ### Dependencies - Python 3.10+ - No external packages required (uses stdlib only) ### Package Structure ``` gitea-ci/ ├── gitea-ci.py Thin wrapper (entry point) ├── style.py Shared styling utilities └── src/gitea_ci/ ├── __init__.py Package metadata, public API ├── __main__.py python -m gitea_ci support ├── cli.py Argument parser, command dispatch ├── config.py Configuration, constants ├── api.py Gitea API client ├── formatters.py Output formatting ├── utils.py Utilities, validation └── commands/ ├── runs.py list, status, logs, watch, delete ├── workflows.py trigger, rerun, cancel, validate ├── artifacts.py artifacts ├── runners.py runners, register-token └── inspect.py stats, pr, compare, infra, config, repo ``` ### Running ```sh ./gitea-ci.py list # Direct execution python3 -m gitea_ci list # Module execution (with PYTHONPATH=src) ``` ## Configuration ### Environment Variables ```sh export GITEA_URL="https://gitea.example.com" export GITEA_TOKEN="your-api-token" ``` ### Config File ```sh gitea-ci config ``` Creates `~/.config/gitea-ci/config.json`: ```json { "url": "https://gitea.example.com", "token": "your-api-token", "default_owner": "myorg", "default_repo": "myproject" } ``` ### Token Permissions Required scopes for full functionality: ``` read:repository List repos, runs, jobs write:repository Trigger, cancel, delete runs read:user User-level runner operations write:admin Runner management (admin only) ``` Test your token: ```sh gitea-ci config --test gitea-ci config token check ``` ## Usage ### Repository Specification Most commands accept repository in multiple formats: ```sh gitea-ci list owner/repo # Positional gitea-ci list -o owner -r repo # Flags gitea-ci list # Uses defaults from config ``` ### Commands #### list (ls, l) List recent workflow runs. ```sh gitea-ci list # List runs (uses default repo) gitea-ci list owner/repo # Specific repository gitea-ci list -n 20 # Show 20 runs gitea-ci list --failed # Only failed runs gitea-ci list --success # Only successful runs gitea-ci list --running # Only running/waiting gitea-ci list -b main # Filter by branch gitea-ci list -w ci.yml # Filter by workflow gitea-ci list --json # JSON output gitea-ci list --compact # Single-line format ``` Without repository specified, discovers all repos with recent runs. #### status (s) Show detailed status of a workflow run. ```sh gitea-ci status owner/repo 123 # Run #123 gitea-ci status -R 123 # Run ID with default repo gitea-ci status owner/repo # Latest run gitea-ci status --json # JSON output ``` #### logs (log) View job logs. ```sh gitea-ci logs owner/repo 123 # All logs for run #123 gitea-ci logs -R 123 # Run ID with default repo gitea-ci logs -R 123 -j 456 # Specific job ``` #### watch (w) Watch workflow runs with live updates. ```sh gitea-ci watch owner/repo # Watch latest run gitea-ci watch -R 123 # Watch specific run gitea-ci watch -i 10 # 10 second refresh gitea-ci watch -t 300 # Timeout after 5 minutes gitea-ci watch --notify # Desktop notification on completion gitea-ci watch --no-clear # Don't clear screen ``` #### stats Show workflow statistics with visual graphs. ```sh gitea-ci stats owner/repo # Statistics for repo gitea-ci stats -n 100 # Analyze last 100 runs gitea-ci stats --detailed # Per-job breakdown gitea-ci stats --json # JSON output ``` #### trigger (t) Trigger a workflow manually (requires workflow_dispatch). ```sh gitea-ci trigger owner/repo -w deploy.yml gitea-ci trigger -w build.yml -b develop gitea-ci trigger -w release.yml -i version=1.2.3 -i env=prod ``` #### rerun Re-run a workflow or specific jobs. ```sh gitea-ci rerun -R 123 # Re-run entire workflow gitea-ci rerun -R 123 -f # Re-run failed jobs only gitea-ci rerun -R 123 -j 456 # Re-run specific job ``` #### cancel Cancel a running workflow. ```sh gitea-ci cancel -R 123 ``` #### delete (rm) Delete a workflow run. ```sh gitea-ci delete -R 123 # Prompts for confirmation gitea-ci delete -R 123 -f # Force delete ``` #### artifacts (art) List and download build artifacts. ```sh gitea-ci artifacts owner/repo # List all artifacts gitea-ci artifacts -R 123 # Artifacts for run #123 gitea-ci artifacts -d 456 # Download artifact #456 gitea-ci artifacts -d 456 -O out.zip ``` #### pr Show CI status for a pull request. ```sh gitea-ci pr owner/repo -p 42 ``` #### compare (diff) Compare two workflow runs. ```sh gitea-ci compare owner/repo 123 456 # Compare run 123 vs 456 gitea-ci compare owner/repo 123 # Compare 123 vs previous gitea-ci compare owner/repo 123 --json ``` #### workflows (wf) List workflow files in a repository. ```sh gitea-ci workflows owner/repo gitea-ci workflows -v # Show triggers and details ``` #### validate (lint) Validate local workflow files. ```sh gitea-ci validate # Current directory gitea-ci validate .gitea/workflows/ gitea-ci validate ci.yml gitea-ci validate --check-runners # Verify runs-on labels gitea-ci validate --strict # Warnings as errors ``` #### runners Manage runners. ```sh gitea-ci runners # List all runners gitea-ci runners list # Same gitea-ci runners info 123 # Runner details gitea-ci runners jobs 123 # Jobs on runner gitea-ci runners delete 123 # Delete runner gitea-ci runners --json # JSON output ``` #### register-token (regtoken) Get runner registration token. ```sh gitea-ci register-token owner/repo # Repo-level token gitea-ci register-token --user # User-level token ``` #### config Configure gitea-ci. ```sh gitea-ci config # Interactive setup gitea-ci config --show # Show current config gitea-ci config --test # Test connectivity gitea-ci config token check # Check token permissions gitea-ci config token set # Set token directly ``` #### repo Repository operations. ```sh gitea-ci repo list # List accessible repos gitea-ci repo exists myrepo # Check if repo exists gitea-ci repo check myrepo # Detailed repo check gitea-ci repo create myrepo # Create repository gitea-ci repo create myrepo -p # Create private repo gitea-ci repo create myrepo -d "Description" ``` #### infra Show infrastructure status. ```sh gitea-ci infra # Runner overview gitea-ci infra --jobs # Show pending/running jobs ``` ## Output Formats ### Standard Output Color-coded with Unicode symbols: ``` ✓ success ✗ failure ⊘ cancelled ● running ○ pending/waiting ◌ queued ``` ### JSON Output Most commands support `--json` for scripting: ```sh gitea-ci list --json | jq '.runs[].id' gitea-ci status -R 123 --json | jq '.jobs[].status' ``` ### Compact Output Single-line format for scripting: ```sh gitea-ci list --compact ``` ## Environment | Variable | Description | Default | |---------------|--------------------------------|----------------------------| | `GITEA_URL` | Gitea instance URL | `https://git.mymx.me` | | `GITEA_TOKEN` | API token | (none) | | `NO_COLOR` | Disable colored output | (not set) | ## Exit Codes | Code | Meaning | |------|------------------------| | 0 | Success | | 1 | General error | | 2 | Authentication failure | ## Examples ### Watch a build after pushing ```sh git push && gitea-ci watch --notify ``` ### Check if CI passed ```sh gitea-ci list --compact | head -1 | grep -q '✓' && echo "CI passed" ``` ### Re-run failed jobs ```sh gitea-ci rerun -R "$(gitea-ci list --compact | head -1 | awk '{print $1}')" -f ``` ### Daily CI summary ```sh gitea-ci list -n 50 --json | jq -r ' .runs | group_by(.conclusion) | map({(.[0].conclusion // "running"): length}) | add' ``` ### Validate before commit ```sh gitea-ci validate --strict && git commit -m "feat: add feature" ``` ## Development ### Module Overview | Module | Lines | Purpose | |--------|-------|---------| | `config.py` | 67 | Config dataclass, constants | | `api.py` | 446 | GiteaAPI class, HTTP handling | | `formatters.py` | 332 | Output formatting, status display | | `utils.py` | 143 | Filtering, validation, notifications | | `cli.py` | 349 | Argument parser, dispatch | | `commands/runs.py` | 461 | Run listing, status, logs, watch | | `commands/workflows.py` | 296 | Trigger, rerun, cancel, validate | | `commands/artifacts.py` | 62 | Artifact operations | | `commands/runners.py` | 188 | Runner management | | `commands/inspect.py` | 842 | Stats, PR, compare, infra, config, repo | ### Import Structure ```python from gitea_ci import Config, GiteaAPI, __version__ from gitea_ci.api import GiteaAPI from gitea_ci.commands import cmd_list, cmd_status ``` ### Validation ```sh # Syntax check all modules python3 -m py_compile src/gitea_ci/*.py src/gitea_ci/commands/*.py # Test import python3 -c "from src.gitea_ci import Config, GiteaAPI; print('OK')" # Test CLI ./gitea-ci.py --help ./gitea-ci.py config --show ``` ## License MIT