configure project

March 2, 2026 · View on GitHub

Manage DevLake projects — create, list, and delete.

A project groups existing connection scopes into a single analytics view with DORA metrics enabled. A blueprint is the sync schedule attached to the project. See concepts.md.

Prerequisites: Run configure scope first to add scopes to your connections.

configure project add

Create a DevLake project, configure its blueprint, and trigger the first data sync.

Usage

gh devlake configure project add [flags]

Flags

FlagDefaultDescription
--project-name(derived from connections or my-project)DevLake project name
--cron0 0 * * *Blueprint sync schedule (cron expression)
--time-after(6 months ago)Only collect data after this date (YYYY-MM-DD)
--skip-syncfalseCreate the project + blueprint but don't trigger the first sync
--waittrueWait for the first pipeline to complete
--timeout5mMax time to wait for pipeline completion

What It Does

  1. Discovers your DevLake instance
  2. Lists all connections (from state file + API)
  3. Prompts you to select which connections to include in the project
  4. For each selected connection, lists its existing scopes
  5. Creates the DevLake project with DORA metrics enabled
  6. Patches the blueprint with the selected connection scopes, cron schedule, and time-after
  7. Triggers the first data sync (unless --skip-sync)
  8. Monitors pipeline progress until completion or --timeout
  9. Updates the state file with project + blueprint info

Pipeline Output

   [10s] Status: TASK_RUNNING | Tasks: 2/8
   [30s] Status: TASK_RUNNING | Tasks: 5/8
   [60s] Status: TASK_COMPLETED | Tasks: 8/8

   ✅ Data sync completed!

The first sync may take 5–30 minutes depending on data volume and how far back --time-after reaches.

Cron Schedule Reference

ScheduleCron Expression
Daily at midnight (default)0 0 * * *
Every 6 hours0 */6 * * *
Hourly0 * * * *
Weekly on Sunday0 0 * * 0

Examples

# Create a project (interactive — discovers connections, prompts for project name)
gh devlake configure project add

# Custom project name
gh devlake configure project add --project-name my-team

# Sync from 1 year ago
gh devlake configure project add --project-name my-team --time-after 2025-01-01

# Create project without triggering sync yet
gh devlake configure project add --skip-sync

# Longer timeout for large repos
gh devlake configure project add --timeout 30m

Notes

  • If a project with --project-name already exists, the command reuses its blueprint ID rather than creating a duplicate.
  • If --time-after is omitted, defaults to 6 months before today.
  • --wait false returns immediately after triggering the sync. Check pipeline status at GET /pipelines/{id} or via status.
  • The project name defaults to the first org found in the state file, or my-project if none is found.

configure project list

List all DevLake projects.

Usage

gh devlake configure project list

Output

Name            Description                               Blueprint ID
──────────────  ────────────────────────────────────────  ────────────
my-team         DevLake metrics for my-team (github)      1
platform        DevLake metrics for platform              2

Supports --json for machine-readable output:

gh devlake configure project list --json

[{"name":"my-team","description":"DevLake metrics for my-team (github)","blueprintId":1}]

configure project delete

Delete a DevLake project by name.

Usage

gh devlake configure project delete [--name <name>]

Flags

FlagDefaultDescription
--name(interactive)Name of the project to delete

Flag mode: --name is required.

Interactive mode: Lists all projects, prompts to select one, then prompts for confirmation.

Examples

# Non-interactive
gh devlake configure project delete --name my-project

# Interactive
gh devlake configure project delete

Warning: Deleting a project removes its associated blueprint and sync schedule. Historical pipeline data for that project will also be removed.