forked from username/gitea-ci
386 lines
8.3 KiB
Markdown
386 lines
8.3 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 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 <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"
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|