Use cases

Four scenarios I actually run, worked end-to-end. Every command and config block here is real and copy-pasteable.

1. Gate a PR on AI risk in CI

The problem. A large or sensitive change lands in a PR and nobody flags it before merge. You want an automatic reviewer that not only comments but can fail the check above a risk threshold you choose.

The setup. Add .github/workflows/gitl-review.yml to your repository:

name: gitl review
on:
  pull_request:

permissions:
  contents: read          # for checkout
  pull-requests: write    # to post the review comment

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0    # required: shallow clones can't resolve base..head

      - uses: akomyagin/gitl@v0.6.2
        with:
          gitl-api-key: ${{ secrets.GITL_API_KEY }}   # BYOK; omit for offline mode
          fail-on: high                               # optional: block merge on high risk

What you get. The Action posts a sticky PR comment with the review and risk level, updated on every push. With fail-on: high the check fails with gitl's exit code 2 when the risk gate triggers — a genuine tool error fails with 1, so downstream steps can tell "risky change" from "gitl broke". Without a key it runs the deterministic offline review: no network, no cost, CI stays green.

GitLab, Bitbucket, and Gitea wrappers exist too — see CI integrations.

2. Pre-commit safety net

The problem. You want a last look at what you're about to commit — without paying an API call on every commit, and without adding latency to the hot path.

The setup. gitl ships a pre-commit framework hook. Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/akomyagin/gitl
    rev: v0.6.2   # pin to a released tag
    hooks:
      - id: gitl-review

then run pre-commit install. To opt into a blocking hook with a cost cap:

hooks:
  - id: gitl-review
    args: [--fail-on=high, --max-cost-usd=0.05]

What you get. gitl review --staged --quiet runs before every commit — offline and free by default (no key, no network). The hook warns but doesn't block unless you opt in. Export GITL_API_KEY if you want a real AI review instead of the heuristic. A plain .git/hooks/pre-commit one-liner works too — see the docs.

3. Release notes in one command

The problem. Writing release notes by scrolling git log is tedious, and raw conventional-commit subjects aren't prose anyone wants to read.

The setup.

# deterministic Keep-a-Changelog output, grouped by conventional commits
gitl changelog

# the model rewrites it as readable release-note prose
GITL_API_KEY=sk-... gitl changelog --ai

What you get. By default: a deterministic changelog from the last tag to HEAD, no LLM involved. With --ai: the model turns the grouped result into release-note prose and reclassifies significant non-conventional commits out of "Other". Without a key (or on a malformed model response) it falls back to the deterministic changelog with a warning — the command never fails, so it's safe to put in a release script.

4. Multi-repo standup digest

The problem. Your work is spread across several repositories, and "what happened here in the last two weeks" means opening each one and scrolling logs.

The setup.

# activity summary across repos, collected in parallel
gitl digest --days=14 --repos=../service-a,../service-b,../infra

# interactive TUI viewer
gitl digest --days=14 --repos=../service-a,../service-b --tui

What you get. Commits, files, and line counts by author and topic per repository — one unreachable repo doesn't fail the rest. The TUI viewer scrolls with j/k or the arrow keys; q quits. JSON output (--format=json) feeds dashboards.

Full documentation →