Introducing Personal Access Tokens for CI/CD Automation

Running ndcli auth login opens a browser window. That works fine on a developer machine — but it is a dead end the moment you try to use it inside a GitHub Actions workflow, a GitLab CI job, or any other unattended automation context. There is no browser, no user, and no way to complete an interactive login.

Personal Access Tokens (PATs) solve this problem. You create a token once from the web app or the CLI, store it as a secret in your pipeline, and from that point on any headless ndcli invocation can authenticate without human interaction.

What a PAT looks like in practice

The typical workflow is three steps:

1. Create the token

This prints a token string once. Copy it — you will not see it again.

2. Store it as a repository secret

In GitHub, go to Settings → Secrets and variables → Actions and add a new secret named NDCLI_TOKEN with the value you just copied.

3. Use it in your workflow

ndcli detects NDCLI_TOKEN in the environment and uses it in place of interactive credentials. No login step required.

Token properties

Scope. Each token is either read-write or read-only. Read-only tokens can list resources and query state but cannot make changes — useful for audit or monitoring jobs that should never accidentally modify anything. The effective permission is always the minimum of the token scope and your role in the target organization, so an RW token used by a read-only member still only gets read access.

Organization scoping. By default a token works across every organization your account belongs to. For tighter control you can optionally restrict it to a single organization — a good practice when a CI pipeline only ever targets one org.

Expiration. Tokens can be created with a fixed expiry (30, 60, 90, 180, or 365 days) or with no expiration at all. Short-lived tokens are the safer default — a leaked token that has already expired is harmless.

Revocation. Any token can be revoked immediately from the web app or via ndcli auth token revoke. Revocation takes effect within seconds across all active sessions. You can create up to 25 tokens per account, so rotating them — create the new one, update the secret, revoke the old one — is straightforward.

See the full documentation

For a complete reference — including how to list and manage existing tokens, rotate them on a schedule, and the exact environment variable names ndcli checks — see the Personal Access Tokens guide.

Join the conversation