gh-log-ci

A GitHub CLI extension that shows CI status next to commit logs

gh log-ci displays recent commits with an inline summary icon of their GitHub Check / Actions status so you can instantly see which commits are green, failing, pending, or cancelled.

gh log-ci works with GitHub.com and GitHub Enterprise Server (any version that supports Checks API).

Requirements: GitHub CLI and Bash 4.0 or newer. macOS ships Bash 3.2 as the default /bin/bash; install a newer Bash first:

brew install bash

The script will detect an unsupported Bash and fail with an actionable error pointing you here.

1. Install GitHub CLI
2. Authenticate: gh auth login
3. (Optional) Ensure you have access to private repos you care about
4. Install the extension: gh extension install xpepper/gh-log-ci (or gh extension install . from local checkout)
5. Run: gh log-ci on a GitHub repo
6. Profit! ✅ 🚀

Basic usage (auto-detect default branch):

gh log-ci

  --branch <name>        Use a specific branch (overrides auto-detect)
  --limit, -n <n>        Number of commits to display (default: 15; env LOG_CI_LIMIT)
  --concurrency, -c <n>  Parallel API calls (default: 4; env LOG_CI_CONCURRENCY)
  --checks, -C           Show per-check run summaries
  --no-spinner           Disable loading spinner (env LOG_CI_NO_SPINNER=1)
  --api-timeout <secs>   Max seconds per API request (default: 30; env LOG_CI_API_TIMEOUT)
  --watch                Continuously poll and update commit statuses
  --watch-interval <s>   Seconds between polls in watch mode (default: 10; env LOG_CI_WATCH_INTERVAL)
  --no-cache             Ignore success cache, force fresh API calls for all commits
  --use-rest             Force REST API mode, bypass GraphQL (env LOG_CI_FORCE_REST=1)
  --help, -h             Show help / usage
  --version              Show version

Help example:

$ gh log-ci --help
gh log-ci - show CI status next to recent commits

Usage:
  gh log-ci [options] [<branch>|<commit-sha>]

Options:
  --branch <name>        Branch to inspect (alternative to positional <branch>)
  --limit, -n <n>        Number of commits to display (default: 15; env LOG_CI_LIMIT overrides)
  --concurrency, -c <n>  Max parallel API calls (default: 4; env LOG_CI_CONCURRENCY overrides)
  --checks, -C           Show per-check run summaries beneath each commit (env LOG_CI_SHOW_CHECKS=1)
  --no-spinner           Disable loading spinner (env LOG_CI_NO_SPINNER=1)
  --api-timeout <secs>   Max seconds per API request (default: 30; env LOG_CI_API_TIMEOUT)
  --watch                Continuously poll and update commit statuses
  --watch-interval <s>   Seconds between polls in watch mode (default: 10; env LOG_CI_WATCH_INTERVAL)
  --no-cache             Ignore success cache, force fresh API calls for all commits
  --use-rest             Force REST API mode, bypass GraphQL (env LOG_CI_FORCE_REST=1)

Branch auto-detect order when <branch> not supplied:
  1. GitHub default branch (via gh repo view)
  2. master (if exists)
  3. main (if exists)
  4. current HEAD branch

Commit SHA mode:
  When a valid commit SHA (full or short) is provided as the first argument,
  gh log-ci displays status for that single commit only.

Examples:
  gh log-ci                                  # auto-detect branch
  gh log-ci main                             # explicit positional branch
  gh log-ci 7b60fc9                          # show status for single commit
  gh log-ci abc123def                        # works with full SHAs too
  gh log-ci --branch develop --limit 30
  gh log-ci -c 8 -n 50                       # increase parallelism and number of commits
  LOG_CI_SHOW_CHECKS=1 gh log-ci -n 10       # show per-check summaries (env)
  gh log-ci -C --limit 5                     # show per-check summaries (flag)
  gh log-ci --watch                          # watch mode (poll every 10s)
  gh log-ci --watch --watch-interval 30      # watch mode with custom interval

Additional environment:
  LOG_CI_WATCH_INTERVAL   Override default poll interval (10)
  LOG_CI_WATCH_ONCE=1     Internal/testing: run only one watch iteration then exit

Exit codes:
  0 success
  1 setup or API error

Specify a branch explicitly:

gh log-ci release-branch

Branch resolution order when no argument is provided:

1. GitHub default branch (gh repo view --json defaultBranchRef --jq .defaultBranchRef.name)
2. master if present
3. main if present
4. Current local HEAD branch

You can also pass a commit SHA (full or short) to check the CI status of a single commit:

# Full commit SHA
gh log-ci 1055e83327fe2415e117ec67fbc8412f9093504f

# Short commit SHA (at least 7 characters)
gh log-ci 1055e83

# Using git rev-parse output
gh log-ci $(git rev-parse HEAD~5)

In commit SHA mode:

• Shows exactly 1 commit (the specified SHA)
• No remote branch warnings
• Works with both GraphQL (default) and REST API modes (--use-rest)
• Accepts both full 40-character SHAs and short SHAs (≥7 characters)

$ gh log-ci
✅  49b3e7623 - (HEAD -> master, origin/master, origin/HEAD) refactor(component): improve caching (Wed Oct 22 15:15:13 2025 +0200) <Jane Doe>
❌  c4f35260a - feat(auth): add MFA (Wed Oct 22 09:25:09 2025 +0200) <John Smith>
🕓  a390e5998 - chore(deps): bump library (Tue Oct 21 16:52:40 2025 +0200) <dependabot[bot]>

By default, gh-log-ci only includes check runs triggered by push events when computing the overall status icon. This prevents scheduled workflows (like Dependabot with event: "dynamic") from incorrectly marking commits as failed.

GitHub associates check suites with the HEAD commit at run time, not the commit that triggered the suite. Without event filtering, workflows triggered by other events would affect the status of otherwise successful commits.

Excluded checks are still displayed when using the -C flag, marked with a 🤖 icon and [non-push] label for visibility.

This behavior matches GitHub's statusCheckRollup logic, which only includes checks from push events.

gh log-ci uses the credentials configured via gh auth login or any supported gh environment variables. Required scopes depend on what you want to read:

Typical token (user) scopes:

• repo (private repository commit metadata & checks)
• read:org (if accessing private org repos)

GitHub App / server-to-server tokens need read access to:

• Repository Contents
• Repository Metadata
• Actions / Checks (implicitly via Checks API)

If you see authentication errors, re-run:

gh auth status
gh auth login

1. Determines input type (branch name or commit SHA).
2. For branch mode: Fetches commits from origin/<branch>. For commit SHA mode: Validates and resolves the SHA.
3. Emits a tab-delimited git log (single commit for SHA mode, last 15 for branch mode).
4. GraphQL batch query (default): Executes a single GraphQL query to fetch check run status for all commits at once (reduces API calls by ~93% for 15 commits). For commit SHA mode, queries the specific commit object.
5. REST API mode (explicit): Use --use-rest flag or LOG_CI_FORCE_REST=1 to make individual REST API calls per commit instead. Required for:
   • GitHub Enterprise Server versions < 3.4 (GraphQL Checks API unavailable)
   • Commits with >100 check suites (GraphQL query limit)
   • Troubleshooting or comparing GraphQL vs REST behavior
6. Maps combined conclusions to an icon and prints decorated line.

By default, gh log-ci uses GraphQL batch queries for optimal performance. Use REST mode (--use-rest or LOG_CI_FORCE_REST=1) when:

• GitHub Enterprise Server < 3.4: GraphQL Checks API not available on older GHES versions
• Commits with >100 check suites: GraphQL query limited to 100 check suites per commit
• GraphQL errors: If you encounter GraphQL API errors, the tool will suggest using --use-rest as a workaround
• Debugging: Comparing behavior between GraphQL and REST API responses

Example:

# Force REST API mode with flag
gh log-ci --use-rest

# Force REST API mode with environment variable
LOG_CI_FORCE_REST=1 gh log-ci

# Combine with other options
gh log-ci --use-rest --concurrency 8 --limit 20

• Branch: positional argument or --branch (auto-detected if omitted).
• Commit count: --limit / -n (default 15) or environment LOG_CI_LIMIT.
• Concurrency: --concurrency / -c (default 4) or environment LOG_CI_CONCURRENCY.
• Per-check detail: --checks / -C or environment LOG_CI_SHOW_CHECKS=1.
• Spinner: disable with --no-spinner or LOG_CI_NO_SPINNER=1.
• API request timeout: --api-timeout <secs> (default 30) or LOG_CI_API_TIMEOUT.
• Watch mode: --watch continuously refresh; --watch-interval <s> (default 10) or LOG_CI_WATCH_INTERVAL.
• Success cache (success-only): TTL LOG_CI_CACHE_TTL (default 86400s / 24h); directory LOG_CI_CACHE_DIR (default ~/.cache/gh-log-ci); debug LOG_CI_CACHE_DEBUG=1.
• Cache bypass: --no-cache to force fresh API calls for all commits.
• Event-based filtering: Non-push workflows excluded from status aggregation; excluded checks displayed with -C marked as [non-push].
• REST API mode: --use-rest flag or LOG_CI_FORCE_REST=1 to bypass GraphQL (required for GHES <3.4).

• Per-check summaries increase output size (consider piping/grep).
• Neutral/skipped/stale checks don't affect overall icon yet.
• No JSON / alternative formats yet.
• Assumes origin remote name.
• GraphQL queries limited to 100 check suites per commit (use --use-rest for commits with >100 suites).
• GraphQL mode only knows about commits that exist on the remote. Querying a local-only (unpushed) commit SHA fails with GraphQL response missing expected data structure; use --use-rest for those.

• Rate-limit handling with backoff + user notice.
• Workflow names and URLs (opt-in with a flag).
• Filtering: author, status, date range, grep on commit message.
• Semantic versioning policy (documented in README).

We use bats for basic behavioral tests and shellcheck for static analysis.

Run locally:

shellcheck gh-log-ci
bats tests

CI runs automatically on pushes / PRs (see .github/workflows/ci.yml).

Convenience local CI script (runs both):

./ci-local.sh

Without Homebrew (alternative via Docker):

docker run --rm -v "$PWD":/work -w /work ubuntu:22.04 bash -c \
  "apt-get update && apt-get install -y bats shellcheck git && bats tests"

For easier development and maintenance, this project includes a Makefile with common tasks:

make help              # List all available tasks
make test              # Run all tests (shellcheck + bats)
make shellcheck        # Run shellcheck only
make bats              # Run bats tests only
make ci-local          # Run local CI script
make clean-cache       # Remove all cache files
make list-cache        # List cache files

See make help for a complete list of available tasks.

1. Fork and clone.
2. Create a feature branch.
3. Make changes + add tests (when available).
4. Open a PR.

See LICENSE.

This tool is under active development. While stable for everyday use, expect new features and improvements in future releases.