gh-devlake

A GitHub CLI extension that deploys, configures, and monitors Apache DevLake from the terminal.

Deploy DevLake locally or on Azure, create connections to GitHub and Copilot, configure DORA project scopes, and trigger data syncs — all without touching the Config UI.

DevLake is an open-source dev data platform that normalizes data from DevOps tools so you can compute consistent engineering metrics like DORA.

This CLI makes that setup fast and repeatable from the terminal (instead of clicking through the Config UI) — especially when you want to re-run the same configuration across teams.

Blog post: Beyond Copilot Dashboards: Measuring What AI Actually Changes — why DORA + Copilot correlation matters and what this tool enables.

Prerequisites

git clone https://github.com/DevExpGBB/gh-devlake.git
cd gh-devlake
go build -o gh-devlake.exe .   # Windows
go build -o gh-devlake .       # Linux/macOS
gh extension install .

Quick Start

gh extension install DevExpGBB/gh-devlake

# Option 1: Fully guided wizard (deploy → connect → scope → project)
gh devlake init

# Option 2: Step-by-step
gh devlake deploy local --dir ./devlake
gh devlake configure full

After setup, open Grafana at http://localhost:3002 (admin / admin). DORA and Copilot dashboards will populate after the first sync completes.

How DevLake Works

Four concepts to understand — then every command makes sense:

For a deeper explanation with diagrams, see DevLake Concepts.

Getting Started Step by Step

Step 1: Deploy

gh devlake deploy local --dir ./devlake

Downloads Docker Compose files, generates secrets, starts the stack, and waits until DevLake is healthy. See docs/deploy.md for flags and details.

gh devlake deploy azure --resource-group devlake-rg --location eastus --official

Step 2: Create Connections

The CLI will prompt you for your PAT. You can also pass --token, use an --env-file, or set GITHUB_TOKEN in your environment. See Token Handling for the full resolution chain.

# GitHub (repos, PRs, workflows, deployments)
gh devlake configure connection add --plugin github --org my-org

# Copilot (usage metrics, seats, acceptance rates)
gh devlake configure connection add --plugin gh-copilot --org my-org

# Jenkins (jobs and build data for DORA)
gh devlake configure connection add --plugin jenkins --endpoint https://jenkins.example.com --username admin --token myapitoken

The CLI tests each connection before saving. On success:

   🔑 Testing connection...
   ✅ Connection test passed
   ✅ Created GitHub connection (ID=1)

See docs/configure-connection.md for all flags.

Step 3: Add Scopes

Tell DevLake which repos or orgs to collect from:

# GitHub — pick repos interactively, or pass --repos explicitly
gh devlake configure scope add --plugin github --org my-org

# Copilot — org-level metrics
gh devlake configure scope add --plugin gh-copilot --org my-org

# Jenkins — pick jobs interactively (or pass --jobs)
gh devlake configure scope add --plugin jenkins --org my-org

DORA patterns (deployment workflow, production environment, incident label) use sensible defaults. See docs/configure-scope.md for overrides.

Step 4: Create a Project and Sync

gh devlake configure project add

Discovers your connections and scopes, creates a DevLake project with DORA metrics enabled, sets up a daily sync blueprint, and triggers the first data collection.

See docs/configure-project.md for flags (--project-name, --cron, --time-after, --skip-sync).

Shortcut: gh devlake configure full chains Steps 2–4 interactively. See docs/configure-full.md.

Day-2 Operations

gh devlake status                                                              # health + summary
gh devlake configure connection list                                           # list connections
gh devlake configure connection update --plugin github --id 1 --token ghp_new # rotate token
gh devlake configure scope add --plugin github --org my-org                    # add more repos
gh devlake cleanup --local                                                     # tear down Docker

Supported Plugins

See Token Handling for env key names and multi-plugin .devlake.env examples.

Command Reference

Global Flags

--json output

Read commands emit a single compact JSON line on success, or {"error":"<message>"} on failure. No emoji, banners, or interactive prompts are printed.

# Human (default)
$ gh devlake status

════════════════════════════════════════
  DevLake Status
════════════════════════════════════════
  ...

# Machine-readable
$ gh devlake status --json
{"deployment":{"method":"local","stateFile":".devlake-local.json"},"endpoints":[{"name":"backend","url":"http://localhost:8080","healthy":true}],"connections":[{"plugin":"github","id":1,"name":"GitHub - my-org","organization":"my-org"}],"project":{"name":"my-project","blueprintId":1}}

# Pipe into jq
$ gh devlake configure connection list --json | jq '.[].name'
"GitHub - my-org"

Commands that support --json:

Additional references: Token Handling · State Files · DevLake Concepts · Day-2 Operations

Development

go build -o gh-devlake.exe .     # Build (Windows)
go build -o gh-devlake .         # Build (Linux/macOS)
go test ./... -v                  # Run tests
gh extension install .            # Install locally for testing

License

MIT — see LICENSE.