Authentication & tokens

ReleaseJet supports per-host and per-repo tokens, so you can use a different token for gitlab.com, a self-hosted company.gitlab.com, and an individual project — without juggling env vars.

Token resolution order

ReleaseJet checks six sources, in order. The first match wins.

#	Source	Example
1	`RELEASEJET_TOKEN` env var (universal)	works for both providers
2	Provider-specific env var	`GITHUB_TOKEN` or `GITLAB_API_TOKEN`
3	Per-repo entry in `~/.releasejet/credentials.yml`	`gitlab.com/myorg/api: glpat-…`
4	Host entry in `~/.releasejet/credentials.yml`	`gitlab.com: glpat-…`
5	Legacy provider-type entry (wildcard fallback)	`gitlab: glpat-…`
6	Bare-text `~/.releasejet/credentials` file	one-line token

Host keys are case-insensitive and lowercased. Default ports 80 (http) and 443 (https) are stripped; non-default ports such as gitlab.example.com:8443 are preserved as-is.

Available since 1.16.0.

`~/.releasejet/credentials.yml`

The YAML file is keyed by host, with optional per-repo overrides:

gitlab.com: glpat-aaaaaaaaaaaaaaaaaaaa             # default for gitlab.com repos
company.gitlab.com: glpat-bbbbbbbbbbbbbbbb         # different host
github.com: ghp_cccccccccccccccccccc               # default for github.com
gitlab.com/personal/sideproject: glpat-dddd        # per-repo override

When several keys could match a request, more specific keys win: per-repo (step 3) beats host (step 4) beats legacy provider-type (step 5).

Worked example

Given:

gitlab: tok-A          # legacy provider-type
gitlab.com: tok-B      # host entry

A request for gitlab.com resolves to tok-B — the host entry matches at step 4.
A request for company.gitlab.com resolves to tok-A — no host entry matches, so it falls through to the legacy GitLab key at step 5.

Setting tokens with `releasejet auth set-token`

Use the CLI to write tokens into credentials.yml without editing the file by hand:

releasejet auth set-token                                   # prompt; auto-detects host from .releasejet.yml
releasejet auth set-token --host company.gitlab.com
releasejet auth set-token --host https://company.gitlab.com # full URL form accepted
releasejet auth set-token --repo gitlab.com/myorg/api

The token is read via a masked password prompt — nothing is echoed to the terminal or written to shell history. Other entries in credentials.yml (other hosts, the Pro pro: block, legacy gitlab: / github: keys) are preserved.

--host and --repo are mutually exclusive. With no flags, ReleaseJet auto-detects the host from .releasejet.yml in the current directory; if no config is present it errors:

Could not auto-detect host. Run from a repo with .releasejet.yml configured, or pass --host explicitly.

Managing tokens

Available since 1.17.0. Four subcommands manage ~/.releasejet/credentials.yml from the CLI without hand-editing.

`auth list-tokens`

Lists every stored token, grouped by kind (Host / Repo / Legacy). Tokens are masked by default — use --show-tokens to reveal them.

releasejet auth list-tokens
releasejet auth list-tokens --show-tokens

Host entries (1):
  gitlab.arx.net  ••••••••

Legacy entries (1):
  github  ••••••••  (deprecated — run `releasejet auth migrate-tokens`)

1 entry skipped (non-string values): license

The mask is always exactly eight bullets, regardless of token length. Sections with zero entries are omitted. Non-string top-level keys (the Pro pro: license block, malformed entries) are skipped from the listing and reported in a stderr warning.

`auth show-token`

Diagnostic. Prints every step of the resolution chain and marks which one was used. Reach for this when the wrong token is being used.

releasejet auth show-token gitlab.com/myorg/api
releasejet auth show-token https://gitlab.com/myorg/api    # full URL form accepted
releasejet auth show-token                                  # auto-detect from current repo
releasejet auth show-token --show-tokens                    # reveal the resolved value

Sample output for an unconfigured host:

Resolving token for gitlab.com/myorg/api

  1. env RELEASEJET_TOKEN                          — not set
  2. env GITLAB_API_TOKEN                          — not set
  3. credentials.yml [gitlab.com/myorg/api]        — not present
  4. credentials.yml [gitlab.com]                  — not present
  5. credentials.yml [gitlab]                      — not present
  6. ~/.releasejet/credentials                     — not present

No token resolved. Run `releasejet auth set-token` to configure.

When a step matches, that line shows match (••••••••) ← used (or the raw token under --show-tokens), and every later step shows (skipped). The legacy step shows (skipped, host matched) when a legacy entry exists but step 4 already matched.

The provider env var on step 2 is GITLAB_API_TOKEN for GitLab hosts and GITHUB_TOKEN for GitHub hosts (inferred via substring match on the host). For GitHub Enterprise on a custom hostname the cosmetic step-2 label may default to GITLAB_API_TOKEN; the actual chain steps 3–6 are unaffected.

When no <repo> argument is passed, the host comes from the current .releasejet.yml's provider.url and the project path is derived from the git origin remote. With no git remote, the command falls back to host-only diagnosis. With neither config nor remote available, it errors:

Could not auto-detect host. Run from a repo with .releasejet.yml configured, or pass <repo> explicitly.

`auth remove-token`

Deletes one entry. Exactly one of --host / --repo / --legacy is required (mutually exclusive).

releasejet auth remove-token --host gitlab.com
releasejet auth remove-token --repo gitlab.com/myorg/api      # accepts full URL too
releasejet auth remove-token --legacy gitlab                  # "gitlab" or "github" only
releasejet auth remove-token --host gitlab.com -y             # skip confirmation

The confirmation prompt defaults to no. Errors non-zero with No credentials file at <path> — nothing to remove. when the file is missing, or No entry found for "<key>". when the key is absent. Other top-level YAML keys (notably the pro: license block) are preserved.

`auth migrate-tokens`

Interactive walkthrough that copies legacy gitlab: / github: entries into host-keyed entries. Recommended cleanup path off legacy keys after upgrading to 1.16.

releasejet auth migrate-tokens

Flow:

Reads credentials.yml. Exits with No legacy entries to migrate. when no gitlab or github keys exist.
For each legacy key (gitlab first, then github): suggests existing host entries that contain the provider name as a substring (heuristic — best-effort, not authoritative). Prompts for a comma-separated list of target hosts; the suggestion list is offered as the prompt default. Empty input skips that legacy key.
For each target host: if it already has a token, prompts <host> already has a token. Overwrite? (default no). Otherwise writes the entry, preserving all sibling YAML keys.
After all visited legacy keys with at least one successful copy, prompts Delete legacy '<provider>' entry now? (default no). The prompt is suppressed when zero copies succeeded — this protects users who declined every overwrite from accidentally deleting their last token.

The Pro pro: license block and any other top-level YAML keys are preserved across all writes.

Backward compatibility

No migration is required. Legacy storage formats keep working indefinitely as wildcard fallbacks:

gitlab: and github: provider-type keys in credentials.yml still resolve any host of that provider not covered by an explicit host entry (step 5).
The bare-text file at ~/.releasejet/credentials (one token per line) still works (step 6).

If you want host-specific tokens, add a host entry — your legacy key stays in place for everything else.

GitHub Actions — Settings → Secrets and variables → Actions → New repository secret
GitLab CI — Settings → CI/CD → Variables → Add variable (mark it masked)

See First CI run for full workflow files.

Troubleshooting

"401 Unauthorized" — wrong scope; regenerate the token with api/repo.
"403 Forbidden" — the token doesn't have access to the repo. Check project-level permissions.
"API token not found" — none of the six sources resolve a token for the requested host. Run releasejet auth set-token or set RELEASEJET_TOKEN.