configure scope

Manage scopes (repos, orgs) on existing DevLake connections.

Scopes define what data DevLake collects from a connection — specific repos for GitHub, jobs for Jenkins, or an org/enterprise for Copilot. This command only manages scopes; it does not create projects or trigger data syncs. After scoping, run configure project add to create a project and start collection.

See concepts.md for what a scope is and how DORA patterns work.

Subcommands

Subcommand	Description
`configure scope add`	Add repo/org/job scopes to a connection
`configure scope list`	List scopes on a connection
`configure scope delete`	Remove a scope from a connection

Aliases: scopes

configure scope add

Add repository, job, or organization scopes to an existing DevLake connection.

Usage

gh devlake configure scope add [flags]

Flags

Flag	Default	Description
`--plugin`	(interactive or required)	Plugin to configure (`github`, `gh-copilot`, `jenkins`, `circleci`, `gitlab`, `bitbucket`, `azuredevops_go`, `jira`, `pagerduty`, `sonarqube`, `argocd`)
`--connection-id`	(auto-detected)	Override the connection ID to scope
`--org`	(plugin-dependent)	Org/workspace slug (`github`, GitLab group path, Bitbucket workspace, Azure DevOps org). Required for plugins whose connection definition needs an org (for example, Azure DevOps) or when running non-interactively; optional in interactive mode for plugins that support workspace discovery (for example, Bitbucket).
`--enterprise`		Enterprise slug (enables enterprise-level Copilot metrics)
`--repos`		Comma-separated repos to add (`owner/repo` for GitHub, `group/project` for GitLab, `workspace/repo-slug` for Bitbucket)
`--repos-file`		Path to a file with repos (one per line: `owner/repo` for GitHub, `group/project` for GitLab, `workspace/repo-slug` for Bitbucket)
`--jobs`		Comma-separated Jenkins job full names
`--projects`		Comma-separated SonarQube project keys
`--deployment-pattern`	`(?i)deploy`	Regex matching CI/CD workflow names for deployments
`--production-pattern`	`(?i)prod`	Regex matching environment names for production
`--incident-label`	`incident`	GitHub issue label that marks incidents

Org requirement: --org is required for plugins that scope by organization/workspace (GitHub, Copilot, GitLab, Bitbucket, Azure DevOps). It is not required for CircleCI, Jenkins, Jira, PagerDuty, SonarQube, or ArgoCD.

Note: --plugin is required when using any other flag. Without flags, the CLI enters interactive mode and prompts for everything.

Alias: azure-devops is accepted as an alias for azuredevops_go.

Repo Resolution

When --repos and --repos-file are both omitted, the CLI uses the GitHub CLI to list up to 100 repos in --org for interactive multi-select.

If the GitHub CLI is unavailable or the list fails, you are prompted to enter repos manually.

DORA Patterns

These patterns are attached to every GitHub repo scope as a scope config. They control how DevLake classifies CI/CD runs and incidents.

Pattern	Default	Controls
`--deployment-pattern`	`(?i)deploy`	Which workflow runs count as deployments
`--production-pattern`	`(?i)prod`	Which environments count as production
`--incident-label`	`incident`	Which issue labels mark incidents

Example for a team using release workflows and live environments:

gh devlake configure scope add --plugin github --org my-org --repos my-org/api \
    --deployment-pattern "(?i)(deploy|release)" \
    --production-pattern "(?i)(prod|live)"

Examples

# Add specific repos to GitHub connection
gh devlake configure scope add --plugin github --org my-org \
    --repos my-org/api,my-org/frontend

# Load repos from a file
gh devlake configure scope add --plugin github --org my-org \
    --repos-file repos.txt

# Interactive repo selection (omit --repos)
gh devlake configure scope add --plugin github --org my-org

# Bitbucket repos (interactive remote-scope picker)
gh devlake configure scope add --plugin bitbucket --org my-workspace

# Add Copilot org scope
gh devlake configure scope add --plugin gh-copilot --org my-org

# Copilot with enterprise scope
gh devlake configure scope add --plugin gh-copilot --org my-org --enterprise my-enterprise

# Jenkins jobs via flags
gh devlake configure scope add --plugin jenkins --org my-org --jobs "team/job1,team/job2"

# Jenkins jobs (interactive remote-scope picker)
gh devlake configure scope add --plugin jenkins --org my-org

# CircleCI projects (interactive)
gh devlake configure scope add --plugin circleci --connection-id 4

# PagerDuty services (interactive)
gh devlake configure scope add --plugin pagerduty --connection-id 5

# Azure DevOps repos (interactive project + repo picker)
# Uses the saved connection's org and endpoint to discover projects and repos
gh devlake configure scope add --plugin azure-devops --org my-azure-org

# Interactive (omit all flags)
gh devlake configure scope add

What It Does (GitHub)

Resolves repos from --repos, --repos-file, or interactive selection
Fetches repo details via gh api repos/<owner>/<repo>
Creates or reuses a DORA scope config (deployment/production patterns, incident label)
Calls PUT /plugins/github/connections/{id}/scopes to add repos

What It Does (Bitbucket)

Resolves workspaces and repos via the DevLake remote-scope API (interactive picker when --repos is omitted)
Accepts repo slugs from --repos / --repos-file (workspace/repo-slug)
Calls PUT /plugins/bitbucket/connections/{id}/scopes with bitbucketId = workspace/repo-slug

What It Does (Copilot)

Computes scope ID from org + enterprise: enterprise/org, enterprise, or org
Calls PUT /plugins/gh-copilot/connections/{id}/scopes to add the org/enterprise scope

What It Does (Jenkins)

Lists Jenkins jobs via the remote-scope API (interactive picker)
Uses --jobs when provided instead of prompting
Calls PUT /plugins/jenkins/connections/{id}/scopes with the selected jobs

What It Does (CircleCI)

Lists followed projects via the DevLake remote-scope API
Prompts for one or more projects to track
Calls PUT /plugins/circleci/connections/{id}/scopes to add the selected projects

What It Does (PagerDuty)

Lists PagerDuty services via the DevLake remote-scope API
Prompts for one or more services to track
Calls PUT /plugins/pagerduty/connections/{id}/scopes with the selected services

What It Does (Azure DevOps)

Uses the saved Azure DevOps connection's org and endpoint to discover remote scopes
Lists projects for that organization via the DevLake remote-scope API
Lets you pick one or more repos within those projects to collect
Calls PUT /plugins/azuredevops_go/connections/{id}/scopes with the selected repos

configure scope list

List all scopes configured on a DevLake plugin connection.

Usage

gh devlake configure scope list [--plugin <plugin>] [--connection-id <id>]

Flags

Flag	Default	Description
`--plugin`	(interactive)	Plugin to query (`github`, `gh-copilot`, `jenkins`, `circleci`, `gitlab`, `bitbucket`, `azuredevops_go`, `jira`, `pagerduty`, `sonarqube`, `argocd`)
`--connection-id`	(interactive)	Connection ID to list scopes for

Flag mode: both --plugin and --connection-id are required.

Interactive mode: Omit both flags — the CLI lists all connections across plugins and lets you pick one.

JSON mode: Pass the global --json flag to output a JSON array instead of a table. --plugin and --connection-id are required in JSON mode (interactive prompts are not supported).

Output

Scope ID    Name              Full Name
──────────  ────────────────  ──────────────────────────────
12345678    api               my-org/api
87654321    frontend          my-org/frontend

Examples

# Non-interactive
gh devlake configure scope list --plugin github --connection-id 1

# Interactive
gh devlake configure scope list

# JSON output (for scripting)
gh devlake configure scope list --plugin github --connection-id 1 --json
# → [{"id":"12345678","name":"api","fullName":"my-org/api"},{"id":"87654321","name":"frontend","fullName":"my-org/frontend"}]

configure scope delete

Remove a scope from an existing DevLake plugin connection.

Usage

gh devlake configure scope delete [--plugin <plugin>] [--connection-id <id>] [--scope-id <scope-id>]

Flags

Flag	Default	Description
`--plugin`	(interactive)	Plugin of the connection (`github`, `gh-copilot`, `jenkins`, `circleci`, `gitlab`, `bitbucket`, `azuredevops_go`, `jira`, `pagerduty`, `sonarqube`, `argocd`)
`--connection-id`	(interactive)	Connection ID
`--scope-id`	(interactive)	Scope ID to delete
`--force`	`false`	Skip confirmation prompt

Flag mode: all three flags are required.

Interactive mode: Omit flags — the CLI picks a connection, lists its scopes, lets you pick one, then prompts for confirmation.

Examples

# Non-interactive
gh devlake configure scope delete --plugin github --connection-id 1 --scope-id 12345678

# Skip confirmation (useful in CI/CD)
gh devlake configure scope delete --plugin github --connection-id 1 --scope-id 12345678 --force

# Interactive
gh devlake configure scope delete

Warning: Deleting a scope removes it from any blueprints that reference it. Projects that depended on this scope will stop collecting data for it.

Next Step

After scoping, run:

gh devlake configure project add --org my-org

concepts.md
configure-connection.md
configure-project.md
configure-full.md — connections + scopes + project in one step

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

configure scope

Subcommands

configure scope add

Usage

Flags

Repo Resolution

DORA Patterns

Examples

What It Does (GitHub)

What It Does (Bitbucket)

What It Does (Copilot)

What It Does (Jenkins)

What It Does (CircleCI)

What It Does (PagerDuty)

What It Does (Azure DevOps)

configure scope list

Usage

Flags

Output

Examples

configure scope delete

Usage

Flags

Examples

Next Step

Related

FilesExpand file tree

configure-scope.md

Latest commit

History

configure-scope.md

File metadata and controls

configure scope

Subcommands

configure scope add

Usage

Flags

Repo Resolution

DORA Patterns

Examples

What It Does (GitHub)

What It Does (Bitbucket)

What It Does (Copilot)

What It Does (Jenkins)

What It Does (CircleCI)

What It Does (PagerDuty)

What It Does (Azure DevOps)

configure scope list

Usage

Flags

Output

Examples

configure scope delete

Usage

Flags

Examples

Next Step

Related