gitea-ci/README.md

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

# 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

export GITEA_URL="https://gitea.example.com"
export GITEA_TOKEN="your-api-token"

Config File

gitea-ci config

Creates ~/.config/gitea-ci/config.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:

gitea-ci config --test
gitea-ci config token check

Usage

Repository Specification

Most commands accept repository in multiple formats:

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.

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.

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.

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.

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.

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).

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.

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.

gitea-ci cancel -R 123

delete (rm)

Delete a workflow run.

gitea-ci delete -R 123             # Prompts for confirmation
gitea-ci delete -R 123 -f          # Force delete

artifacts (art)

List and download build artifacts.

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.

gitea-ci pr owner/repo -p 42

compare (diff)

Compare two workflow runs.

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.

gitea-ci workflows owner/repo
gitea-ci workflows -v              # Show triggers and details

validate (lint)

Validate local workflow files.

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.

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.

gitea-ci register-token owner/repo # Repo-level token
gitea-ci register-token --user     # User-level token

config

Configure gitea-ci.

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.

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.

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:

gitea-ci list --json | jq '.runs[].id'
gitea-ci status -R 123 --json | jq '.jobs[].status'

Compact Output

Single-line format for scripting:

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

git push && gitea-ci watch --notify

Check if CI passed

gitea-ci list --compact | head -1 | grep -q '✓' && echo "CI passed"

Re-run failed jobs

gitea-ci rerun -R "$(gitea-ci list --compact | head -1 | awk '{print $1}')" -f

Daily CI summary

gitea-ci list -n 50 --json | jq -r '
  .runs | group_by(.conclusion) |
  map({(.[0].conclusion // "running"): length}) | add'

Validate before commit

gitea-ci validate --strict && git commit -m "feat: add feature"

License

MIT