Automation tokens

For everyday development, use rvs auth login. The CLI stores your session in a secure credential store and supplies temporary credentials to package tools, so you do not need to handle an automation token.

Choose the right token

Token	Who owns it	What it can access
Personal-account PAT (rvs_ust…)	You	Selected resources in your personal account
Organization-account PAT (rvs_uot…)	You	Selected resources in one organization, limited by your current access and namespace membership
Organization automation token (rvs_oat…)	The organization	Selected organization resources for CI or a secret manager

A personal access token (PAT) always targets one account. Your personal-account PAT never gains organization access. Create a separate organization-account PAT for work you perform as an organization member. Removing that membership removes its access; organization-owned automation does not depend on its creator remaining a member.

Organization administrators can create organization-owned automation tokens for any permitted organization resource. A namespace administrator can create one from the namespace’s Automation tokens section; Ravenstash permanently restricts that token to exactly that namespace. Namespace administrators cannot create unrestricted, multi-namespace, or private-mirror grants. Use organization-owned tokens for shared builds and release jobs.

Create and restrict a token

1. Open your personal-token settings and select the personal or organization account the token will access. For shared CI, open the organization’s automation-token settings. A namespace administrator opens Automation tokens inside the namespace instead.
2. Give the token a name that identifies its purpose.
3. Next to Account to access, an organization administrator can optionally select one or more namespaces under Namespace resources restriction. This restriction is permanent and applies only to resources within namespaces; remote caches remain independently selectable. In namespace settings, the current namespace is already selected and cannot be removed.
4. Add Artifacts repository, Remote cache, or both from the choices shown for your boundary. For repositories, choose all current and future repositories within the account or selected namespaces, or select individual repositories. For remote caches, choose all official and custom caches, all official caches, or individual caches. Namespace administrators see only repository choices inside their namespace and cannot add remote-cache grants.
5. Choose permissions for each resource. Nothing is selected by default. Repository Reader downloads packages; Publisher also uploads them; Admin provides full repository management. Remote cache Install installs directly from private mirrors and is offered when your private-mirror access covers the selected caches; Repository upstream lets the token connect the cache as a source of repositories it manages; Admin also manages caches, age policies, origin credentials, and cached package deletion. Creating custom caches requires All remote caches with Admin.
6. Set an expiration, create the token, and copy its one-time secret into your approved secret manager.

Token grants never give a member access beyond their current access. An organization-account PAT works only in namespaces you belong to and only with the permissions your roles currently include there. When you choose Admin, the token receives just the permissions you currently hold for the whole selection, such as those of a Maintainer, and a later promotion does not widen an existing token. If you leave a namespace, lose a role, or are suspended, the token loses that access too. The Admin repository permission does not grant account administration.

A namespace-restricted organization token does not depend on its creator remaining a namespace administrator. Another namespace administrator or an organization administrator can rotate or revoke it when the workflow changes.

Use the token with rvs

Expose the secret to the CI job as RVS_TOKEN. rvs uses it to obtain temporary package credentials. A present RVS_TOKEN overrides the stored login session; an invalid or empty value fails instead of using that session.

While RVS_TOKEN is set, rvs acts for the account the token belongs to, so you do not need to choose an account. Your saved account choice does not apply until you remove the token.

Keep a separate token for each workflow so it can be restricted and revoked independently. Never commit or log a token, bake it into an image, or put it in a cache key.

Direct package-tool access

Prefer the rvs wrappers. Direct use of a PAT or organization automation token in a native registry is strongly discouraged and may be removed in the future. If a tool cannot run through rvs, generate a short-lived token and use it only for the required operation.

Direct use is enabled by default but can be disabled independently for personal-account PATs, organization-account PATs, and organization-owned automation. You control the personal-account setting; organization administrators control the two organization settings. Disabling direct use does not disable exchanging an otherwise authorized token through rvs.

Rotate or revoke

Rotation shows a new secret once and replaces the old secret. Update the secret manager promptly. To migrate jobs without an interruption, create a separate replacement token, move and test the jobs, then revoke the old token.

Access edits, rotation, and revocation invalidate existing derived credentials. Check the operation’s completion status before assuming cached access has stopped everywhere. Rotate or revoke credentials after suspected exposure.