gitl

gitl

AI-powered git history reviewer for CLI and CI. gitl (git-log-lens) reads a repository's git history and turns it into a structured engineering artifact via LLM:

• gitl review <range> — AI review of a commit range / PR with machine-readable risk scoring (low|medium|high) for CI gating (--fail-on=high → non-zero exit code);
• gitl changelog [<range>] — Keep a Changelog-style changelog, grouped by conventional commits (defaults to last tag → HEAD);
• gitl digest [--days=N] [--repos=a,b,c] — activity summary by author/topic/file, including multiple repositories in parallel.

A clean CLI binary plus a GitHub Action wrapper — no server, no database, no hosted key storage. BYOK (bring your own key) with multi-provider support: OpenAI-compatible API, Ollama (local/self-hosted), Azure OpenAI. No telemetry.

Status: MVP complete. All three commands (review/changelog/digest) work on real repositories with all three output formats (md|text|json). The Action posts AI reviews as sticky PR comments and gates on risk score. The latest tagged release, v0.2.1, ships cross-compiled, cosign-signed release binaries. SLSA L3 build provenance alongside cosign signatures is implemented on main and will ship with the next tag, v0.3.0 (see VERIFY.md for verification). Marketplace listing is the remaining manual step.

Quick start

Requires Go 1.22+ and git in PATH.

# build
go build ./...

# AI review of a commit range (no key = deterministic offline review)
go run ./cmd/gitl review HEAD~5..HEAD

# with a key — real review via OpenAI-compatible API with risk scoring
GITL_API_KEY=sk-... go run ./cmd/gitl review HEAD~5..HEAD

# machine-readable output for CI + risk gating
go run ./cmd/gitl review HEAD~5..HEAD --format=json
go run ./cmd/gitl review HEAD~5..HEAD --fail-on=high   # non-zero exit on high risk

# estimate cost without making an API call
go run ./cmd/gitl review HEAD~5..HEAD --dry-run

# changelog from last tag (or full history if no tags) — no LLM
go run ./cmd/gitl changelog
go run ./cmd/gitl changelog v1.2.0..HEAD --format=json

# activity summary for the last N days — no LLM
go run ./cmd/gitl digest --days=14

# multi-repo digest: runs in parallel; one unreachable repo does not fail the rest
go run ./cmd/gitl digest --repos=../service-a,../service-b --format=json

go run ./cmd/gitl version
go run ./cmd/gitl --help

# tests
go test ./...

Install:

# Go toolchain
go install github.com/akomyagin/gitl/cmd/gitl@latest

# Homebrew (macOS/Linux)
brew install akomyagin/tap/gitl

# Or download a signed release binary from GitHub Releases (see VERIFY.md)

Local multi-provider test (Ollama)

docker-compose.yml starts only the dev dependency — a local Ollama instance for testing the multi-provider LLM client (gitl itself is not containerized):

docker compose up ollama

Configuration

Two levels, merged by priority: flag > env > .gitl.yaml (repo) > ~/.config/gitl/config.yaml (personal). The repo-level .gitl.yaml is committed as a shared team policy (risk threshold, excluded paths, changelog categories). Without a key, gitl runs in deterministic offline mode.

In offline mode — or when a real model omits a valid risk block and gitl falls back to the heuristic — the risk header is annotated with *(heuristic)* (and "heuristic": true in --format=json), so a deterministic score is never mistaken for a model's own judgement.

Providers (llm.provider)

# OpenAI-compatible API (default)
llm:
  provider: "openai"
  api_key: ""            # or env GITL_API_KEY
  base_url: "https://api.openai.com/v1"
  model: "gpt-4o-mini"

# Ollama — local/self-hosted, no key, free
llm:
  provider: "ollama"
  base_url: "http://localhost:11434/v1"
  model: "llama3.1"

# Azure OpenAI — custom auth/endpoint format
llm:
  provider: "azure_openai"
  api_key: ""             # or env GITL_API_KEY
  model: "gpt-4o-mini"    # used only for cost estimation
  azure_openai:
    endpoint: "https://<resource>.openai.azure.com"
    deployment: "<deployment-name>"
    api_version: "2024-08-01-preview"

GitHub Action

gitl can be wired up as a GitHub Action: it AI-reviews a pull request's commits and posts a comment with the risk score, optionally blocking merge above a threshold. The Action builds gitl from source (go install at a pinned version).

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@v4
        with:
          fetch-depth: 0    # required: without full history base..head won't resolve

      - uses: akomyagin/gitl@v0.2.1
        with:
          gitl-api-key: ${{ secrets.GITL_API_KEY }}   # BYOK, see below
          fail-on: high                               # optional: block merge on high risk

Security best practices:

• Key via secrets.* only. gitl-api-key comes from secrets.GITL_API_KEY (set under Settings → Secrets and variables → Actions), never hardcoded in YAML or committed. If the secret is not set, the Action runs in deterministic offline mode (no network, no cost).
• Minimal permissions:. Only pull-requests: write (posting the comment) and contents: read (checkout) are needed — do not grant broader rights.
• fetch-depth: 0 is required. GitHub provides base/head SHAs in the pull_request event, but a shallow clone won't resolve base.sha..head.sha.
• fail-on defaults to never. The Action only comments; it does not block merges unless you opt in explicitly (fail-on: high, etc.) — same "WARN by default, hard gate is explicit opt-in" principle as the CLI (--fail-on).
• Diff privacy. In CI, the diff is sent to whichever LLM provider is configured (default: OpenAI-compatible API). For private code, use a self-hosted/enterprise provider (Ollama, Azure OpenAI) — see Providers above.
• Secret masking. GitHub automatically masks secrets.* values in runner logs as ***, but that's not a reason to print the key in your own workflow steps.

License

MIT.