configure connection

Create, list, test, update, and delete DevLake plugin connections.

A connection is an authenticated link to a data source. Each plugin gets its own connection with its own PAT. See concepts.md for background.

configure connection (create)

Create a plugin connection in DevLake using a PAT.

Usage

gh devlake configure connection [flags]

Aliases: connections

Flags

Flag	Default	Description
`--plugin`	(interactive)	Plugin to configure (`github`, `gh-copilot`, `jenkins`, `circleci`, `gitlab`, `bitbucket`, `azuredevops_go`, `jira`, `pagerduty`, `sonarqube`, `argocd`)
`--org`	(plugin-dependent)	Organization/group/workspace slug (required for GitHub, GitLab, and Azure DevOps; for Azure DevOps, use the organization segment from `https://dev.azure.com/<org>`; optional for Copilot when `--enterprise` is provided)
`--enterprise`		GitHub enterprise slug (Copilot only)
`--name`	`Plugin - org`	Connection display name
`--endpoint`	(plugin default when available)	API endpoint override (required for Jenkins, Azure DevOps, Jira, SonarQube, and ArgoCD because they have no default endpoint; for Azure DevOps, usually `https://dev.azure.com/<org>`)
`--proxy`		HTTP proxy URL
`--token`		Plugin PAT or API token (highest priority source). For BasicAuth plugins (Jenkins, Bitbucket), this is the password/app token.
`--username`		Username for BasicAuth plugins (Jenkins, Bitbucket). Ignored for token-based plugins.
`--env-file`	`.devlake.env`	Path to env file containing PAT
`--skip-cleanup`	`false`	Don't delete `.devlake.env` after setup

Required PAT Scopes

Plugin	Required Scopes
`github`	`repo`, `read:org`, `read:user`
`gh-copilot`	`manage_billing:copilot`, `read:org`
`gh-copilot` (enterprise metrics)	+ `read:enterprise`
`jenkins`	Username + API token/password (BasicAuth)
`circleci`	Personal API token (Circle-Token header)
`gitlab`	`read_api`, `read_repository`
`bitbucket`	App password (BasicAuth; no scopes)
`azuredevops_go`	Azure DevOps PAT (no scopes)
`jira`	API token (no scopes)
`pagerduty`	API key (sent as `Token token=<key>`)
`sonarqube`	API token (no scopes)
`argocd`	Auth token (no scopes)

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

Org requirement: --org is required for GitHub, GitLab, and Azure DevOps connections. Copilot accepts either --org, --enterprise, or both. CircleCI, Bitbucket, Jenkins, Jira, PagerDuty, SonarQube, and ArgoCD do not require --org at connection-creation time.

Token Resolution Order

For each plugin, the CLI resolves the PAT in this order (see token-handling.md for the full guide):

--token flag
.devlake.env file — checked for plugin-specific keys:
- GitHub / Copilot: GITHUB_PAT, GITHUB_TOKEN, or GH_TOKEN
- Azure DevOps: AZURE_DEVOPS_PAT or AZDO_PAT
Plugin-specific environment variable (same key names, from shell environment)
Interactive masked prompt (terminal fallback)

Username Resolution (BasicAuth plugins)

For plugins that use BasicAuth (e.g. Jenkins, Bitbucket, Jira), the --username flag is resolved in this order:

--username flag
.devlake.env file — checked for plugin-specific keys (e.g. JENKINS_USERNAME)
Plugin-specific environment variable (from shell environment)
Interactive prompt (terminal fallback)

When --username is provided for a plugin that uses AccessToken auth (like GitHub or Copilot), the CLI prints a warning that the flag is not applicable.

What It Does

Auto-discovers DevLake instance (state file → localhost ports → --url)
Resolves the PAT using the resolution chain above
Displays required PAT scopes as a reminder (regardless of token source)
Prompts for connection name and proxy (Enter accepts defaults / skips)
For GitHub: offers Cloud vs. Enterprise Server endpoint choice
Tests the connection before saving
Calls POST /plugins/{plugin}/connections
Saves the connection ID to the state file
Deletes .devlake.env (unless --skip-cleanup)

Examples

# GitHub connection (interactive token prompt if .devlake.env not present)
gh devlake configure connection --plugin github --org my-org

# Copilot connection
gh devlake configure connection --plugin gh-copilot --org my-org

# Jenkins connection (endpoint required)
gh devlake configure connection --plugin jenkins --endpoint https://jenkins.example.com --username admin

# CircleCI connection
gh devlake configure connection --plugin circleci --name "CircleCI - backend"

# PagerDuty connection
gh devlake configure connection --plugin pagerduty --name "PagerDuty - oncall"

# Enterprise Copilot metrics
gh devlake configure connection --plugin gh-copilot --org my-org --enterprise my-enterprise

# GitHub Enterprise Server
gh devlake configure connection --plugin github --org my-org \
    --endpoint https://github.example.com/api/v3/

# With proxy
gh devlake configure connection --plugin github --org my-org --proxy http://proxy:8080

# BasicAuth plugin (e.g. Jenkins)
gh devlake configure connection --plugin jenkins --username admin --token mypassword

# Azure DevOps connection
# --org is the organization segment from https://dev.azure.com/<org>
# --endpoint should usually match: https://dev.azure.com/<org>
gh devlake configure connection --plugin azuredevops_go --org my-azure-org \
    --endpoint https://dev.azure.com/my-azure-org

# Azure DevOps via alias, with PAT from AZDO_PAT or AZURE_DEVOPS_PAT
export AZDO_PAT=my-pat
gh devlake configure connection --plugin azure-devops --org my-azure-org \
    --endpoint https://dev.azure.com/my-azure-org

# Interactive (no --plugin — prompts for everything)
gh devlake configure connection

Output

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

configure connection list

List all plugin connections in DevLake.

Usage

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

Flags

Flag	Default	Description
`--plugin`	(all plugins)	Filter output to one plugin (`github`, `gh-copilot`, `jenkins`, `circleci`, `gitlab`, `bitbucket`, `azuredevops_go`, `jira`, `pagerduty`, `sonarqube`, `argocd`)

Output

Plugin       ID  Name                         Organization  Enterprise
──────────   ──  ──────────────────────────   ────────────  ──────────
github        1  GitHub - my-org              my-org
gh-copilot    2  GitHub Copilot - my-org      my-org        avocado-corp

configure connection test

Test an existing DevLake connection by plugin and ID.

Usage

gh devlake configure connection test [--plugin <plugin>] [--id <id>]

Flags

Flag	Default	Description
`--plugin`	(interactive)	Plugin to test (`github`, `gh-copilot`, `jenkins`, `circleci`, `gitlab`, `bitbucket`, `azuredevops_go`, `jira`, `pagerduty`, `sonarqube`, `argocd`)
`--id`	`0`	Connection ID to test

Both flags are required for non-interactive mode. If either is omitted, the CLI prompts interactively.

Output

✅ Connection test passed

❌ Connection test failed: <error message>
   💡 Ensure your PAT has these scopes: repo, read:org, read:user

configure connection update

Update an existing connection in-place. Use for token rotation, endpoint changes, or org/enterprise updates. Preserves scope configs and blueprint associations.

Usage

gh devlake configure connection update [--plugin <plugin>] [--id <id>] [update flags]

Flags

Flag	Default	Description
`--plugin`	(interactive)	Plugin slug (`github`, `gh-copilot`, `jenkins`, `circleci`, `gitlab`, `bitbucket`, `azuredevops_go`, `jira`, `pagerduty`, `sonarqube`, `argocd`)
`--id`	(interactive)	Connection ID to update
`--token`		New PAT for token rotation
`--org`		New organization slug
`--enterprise`		New enterprise slug
`--name`		New connection display name
`--endpoint`		New API endpoint URL
`--proxy`		New HTTP proxy URL

Flag mode: --plugin and --id are both required. Only fields you specify are changed.

Interactive mode: Omit --plugin or --id. The CLI lists existing connections, lets you pick one, then shows current values as defaults (press Enter to keep any field unchanged).

Examples

# Token rotation
gh devlake configure connection update --plugin github --id 1 --token ghp_newtoken

# Change org
gh devlake configure connection update --plugin gh-copilot --id 2 --org new-org

# Interactive
gh devlake configure connection update

configure connection delete

Delete a plugin connection from DevLake.

Usage

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

Flags

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

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

Interactive mode: Lists all connections across plugins, prompts to select one, then prompts for confirmation.

Example

# Non-interactive
gh devlake configure connection delete --plugin github --id 3

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

# Interactive
gh devlake configure connection delete

Warning: Deleting a connection removes its associated scopes from any blueprints that reference them. Projects that depended on this connection will stop collecting data for those scopes.

concepts.md — what a connection is
token-handling.md — PAT resolution, .devlake.env, security notes
configure-scope.md — add scopes to a connection
configure-project.md — create a project that uses connections
configure-full.md — create connections + scopes + project in one step

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

configure connection

configure connection (create)

Usage

Flags

Required PAT Scopes

Token Resolution Order

Username Resolution (BasicAuth plugins)

What It Does

Examples

Output

configure connection list

Usage

Flags

Output

configure connection test

Usage

Flags

Output

configure connection update

Usage

Flags

Examples

configure connection delete

Usage

Flags

Example

Related

FilesExpand file tree

configure-connection.md

Latest commit

History

configure-connection.md

File metadata and controls

configure connection

configure connection (create)

Usage

Flags

Required PAT Scopes

Token Resolution Order

Username Resolution (BasicAuth plugins)

What It Does

Examples

Output

configure connection list

Usage

Flags

Output

configure connection test

Usage

Flags

Output

configure connection update

Usage

Flags

Examples

configure connection delete

Usage

Flags

Example

Related