# 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 or copy gitea-ci.py and style.py to your PATH cp gitea-ci.py style.py ~/.local/bin/ chmod +x ~/.local/bin/gitea-ci.py # Or symlink ln -s "$(pwd)/gitea-ci.py" ~/.local/bin/gitea-ci ``` ### Dependencies - Python 3.10+ - No external packages required (uses stdlib only) ## 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" ``` ## License MIT