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

./gitea-ci.py list                   # Direct execution
python3 -m gitea_ci list             # Module execution (with PYTHONPATH=src)

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"

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

from gitea_ci import Config, GiteaAPI, __version__
from gitea_ci.api import GiteaAPI
from gitea_ci.commands import cmd_list, cmd_status

Validation

# 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