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.

Note

GitHub Copilot plugin: The Copilot metrics plugin is currently available in the DevExpGBB/incubator-devlake fork while the upstream PR (apache/incubator-devlake#8728) is under review. The deploy local and deploy azure commands handle custom images automatically — no manual image builds needed. Once the PR merges, the official Apache images will include it.

---

Prerequisites

Requirement	When needed
GitHub CLI (gh)	Always — this is a gh extension
Docker	deploy local, cleanup --local
Azure CLI (az)	deploy azure only
GitHub PAT	Required when creating connections (see Supported Plugins)

Building from source

Requires Go 1.22+.

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
cd devlake && docker compose up -d
# wait ~2 minutes, then:
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.

Service	URL
Grafana	http://localhost:3002 (admin/admin)
Config UI	http://localhost:4000
Backend API	http://localhost:8080

---

How DevLake Works

Four concepts to understand — then every command makes sense:

Concept	What It Is
Connection	An authenticated link to a data source (GitHub, Copilot). Each gets its own PAT.
Scope	What to collect — specific repos for GitHub, an org/enterprise for Copilot.
Project	Groups connections + scopes into a single view with DORA metrics enabled.
Blueprint	The sync schedule (cron). Created automatically with the project.

For a deeper explanation with diagrams, see DevLake Concepts.

---

Getting Started Step by Step

Step 1: Deploy

gh devlake deploy local --dir ./devlake
cd devlake && docker compose up -d

Downloads Docker Compose files, generates secrets, and prepares the stack. Give it ~2 minutes after docker compose up. See docs/deploy.md for flags and details.

Deploying to Azure instead

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

Creates Container Instances, MySQL Flexible Server, and Key Vault via Bicep (~$30–50/month with --official). Omit flags to be prompted interactively.

See docs/deploy.md for all Azure options, custom image builds, and tear-down.

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 --plugin github --org my-org

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

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 --plugin github --org my-org

# Copilot — org-level metrics
gh devlake configure scope --plugin gh-copilot --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

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

Status checks, token rotation, adding repos, and tear-down

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 --plugin github --org my-org                        # add more repos
gh devlake cleanup --local                                                     # tear down Docker

For the full guide, see Day-2 Operations.

---

Supported Plugins

Plugin	Status	What It Collects	Required PAT scopes
GitHub	✅ Available	Repos, PRs, issues, workflows, deployments (DORA)	repo, read:org, read:user
GitHub Copilot	✅ Available	Usage metrics, seats, acceptance rates	manage_billing:copilot, read:org (+ read:enterprise for enterprise metrics)
Azure DevOps	🔜 Coming soon	Repos, pipelines, deployments (DORA)	(TBD)
GitLab	🔜 Coming soon	Repos, MRs, pipelines, deployments (DORA)	(TBD)

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

---

Command Reference

Command	Description	Docs
gh devlake init	Guided 4-phase setup wizard	init.md
gh devlake status	Health check and connection summary	status.md
gh devlake deploy local	Local Docker Compose deploy	deploy.md
gh devlake deploy azure	Azure Container Instance deploy	deploy.md
gh devlake configure connection	Create a plugin connection	configure-connection.md
gh devlake configure connection list	List all connections	configure-connection.md
gh devlake configure connection test	Test a saved connection	configure-connection.md
gh devlake configure connection update	Rotate token or update settings	configure-connection.md
gh devlake configure connection delete	Remove a connection	configure-connection.md
gh devlake configure scope	Add repo/org scopes to a connection	configure-scope.md
gh devlake configure project	Create project + blueprint + first sync	configure-project.md
gh devlake configure full	Connections + scopes + project in one step	configure-full.md
gh devlake cleanup	Tear down local or Azure resources	cleanup.md

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.