forked from username/gitea-ci
add documentation and cheatsheet
This commit is contained in:
Username
385
README.md
Normal file
385
README.md
Normal file
@@ -0,0 +1,385 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user