Skip to content

token-handling.md

Latest commit

 

History

History
85 lines (58 loc) · 3.73 KB

token-handling.md

File metadata and controls

85 lines (58 loc) · 3.73 KB

Token Handling

How the CLI resolves, uses, and secures Personal Access Tokens (PATs) for each plugin connection.

Supported today: GitHub, GitHub Copilot, GitLab, Azure DevOps.

Token Resolution Order

For each plugin connection, the CLI resolves the PAT using this priority chain — first match wins:

Priority Source Example
1 --token flag --token ghp_abc123
2 --env-file file (default: .devlake.env) File containing GITHUB_TOKEN=ghp_abc123
3 Shell environment variable Plugin-specific key (see below)
4 Interactive masked prompt CLI prompts at the terminal (TTY required)

If none of these produce a token, the command fails.

Using a .devlake.env File

Create a file with one or more tokens:

GITHUB_TOKEN=ghp_your_token_here
GITLAB_TOKEN=glpat_your_token_here
AZURE_DEVOPS_PAT=ado_pat_here

The CLI checks plugin-specific keys (first match wins):

Plugin .devlake.env keys (in order) Environment variables (in order)
GitHub GITHUB_PAT, GITHUB_TOKEN, GH_TOKEN GITHUB_PAT, GITHUB_TOKEN, GH_TOKEN
GitHub Copilot GITHUB_PAT, GITHUB_TOKEN, GH_TOKEN GITHUB_PAT, GITHUB_TOKEN, GH_TOKEN
GitLab GITLAB_TOKEN, GITLAB_PAT GITLAB_TOKEN, GITLAB_PAT
Azure DevOps AZURE_DEVOPS_PAT, AZDO_PAT AZURE_DEVOPS_PAT, AZDO_PAT

By default, the CLI looks for .devlake.env in the current directory. Override the path with --env-file:

gh devlake configure connection --plugin github --org my-org --env-file ./tokens/my.env

Environment Variables

If no --token flag or env file is found, the CLI checks your shell environment using the plugin-specific key names in the table above.

Interactive Prompt

As a final fallback, the CLI prompts you to paste the token at the terminal. Input is masked (hidden). This requires a TTY — it won't work in piped/non-interactive shells.

Required PAT Scopes

Plugin Required Scopes
GitHub repo, read:org, read:user
GitHub Copilot manage_billing:copilot, read:org
GitHub Copilot (enterprise) + read:enterprise
GitLab read_api, read_repository
Azure DevOps PAT with repo + pipeline access (no OAuth scopes)

The CLI displays required scopes as a reminder before prompting for the token.

Security

  • Never in history or logs. The token is never echoed to the terminal, written to command history, or included in log output.
  • Encrypted at rest. After a successful connection, the token is stored encrypted in DevLake's MySQL database using the ENCRYPTION_SECRET generated during deployment.
  • .gitignore by default. The .devlake.env file is listed in the default .gitignore created by deploy local.

Cleanup Behavior

Command .devlake.env after success
configure connection Deleted automatically (use --skip-cleanup to keep it)
configure full Deleted automatically (use --skip-cleanup to keep it)
init Deleted automatically (use --skip-cleanup to keep it)

Cleanup only happens when the token was loaded from an env file (i.e., the command actually used --env-file). If you provided the token via --token, shell env vars, or the interactive prompt, there's no file to delete.

Related