forked from username/gitea-ci
8d05e90160
Split monolithic gitea-ci.py (3068 lines) into modular package: - src/gitea_ci/config.py: configuration, constants - src/gitea_ci/api.py: GiteaAPI class - src/gitea_ci/formatters.py: output formatting - src/gitea_ci/utils.py: utilities, validation - src/gitea_ci/commands/: command implementations - src/gitea_ci/cli.py: argument parser, dispatch gitea-ci.py now thin wrapper (16 lines)
458 lines
11 KiB
Markdown
458 lines
11 KiB
Markdown
# 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 <token> # 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
|