configure connection

March 11, 2026 · View on GitHub

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