Gitlab Token
@sntxrr/gitlab-tokenv2026.08.19.2
01README
Create, rotate, revoke and inventory GitLab personal, project and group access tokens through one model, with a threshold-gated rotation workflow and the one-time token value written to a vaulted sensitive field
02Models
@sntxrr/gitlab-tokenv2026.08.19.1gitlab_token.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| token | string | GitLab token used to authenticate these API calls, sent as PRIVATE-TOKEN. |
| baseUrl | string | GitLab instance base URL, without the /api/v4 suffix. Override for self-managed. |
| tokenScope | enum | Which token family this instance manages: personal, project, or group. |
| namespace? | string | Project path (group/repo) or group path owning the token, URL-encoded |
| tokenId? | string | ID of the token this model manages. Also accepts the literal `self` to |
| userId? | string | User ID to create a personal access token for. Requires instance |
| timeoutMs | number | Abort any single API request after this long. |
fn sync()
Fetch one token's current metadata.
fn create(name: string, scopes: array, expiresAt?: string, description?: string, accessLevel: enum)
Provision a new token; writes its metadata and its one-time value.
| Argument | Type | Description |
|---|---|---|
| name | string | Name of the new token. |
| scopes | array | Scopes to grant, e.g. [api] or [read_repository, read_registry]. A |
| expiresAt? | string | Expiry date as YYYY-MM-DD. Omit to take the instance's maximum allowable |
| description? | string | Free text carried on the token, up to 255 characters. |
| accessLevel | enum | Role the token acts as. Project and group tokens only; ignored for personal. |
fn rotate(expiresAt?: string, when: boolean)
Rotate the token: GitLab revokes the current value and issues a new one under a new ID.
| Argument | Type | Description |
|---|---|---|
| expiresAt? | string | Expiry date for the replacement token as YYYY-MM-DD. Omit to take |
| when | boolean | Rotate only when true. Exists because swamp workflows cannot express |
fn delete(when: boolean)
Revoke the token. Already-revoked is treated as success, not an error.
| Argument | Type | Description |
|---|---|---|
| when | boolean | Revoke only when true. Same rationale as the argument of the same name |
fn list(state: enum, search?: string, expiresBefore?: string)
Discover every token in the configured scope (factory); writes one snapshot each.
| Argument | Type | Description |
|---|---|---|
| state | enum | Filter by token state. `all` omits the filter and returns both. |
| search? | string | Filter by token name. |
| expiresBefore? | string | Only tokens expiring before this date (YYYY-MM-DD). Use to find what is |
Resources
token(infinite)— Snapshot of a token's metadata — scopes, expiry, days remaining, last use. Never the value.
secret(infinite)— A token value as disclosed once by create or rotate, in a vaulted sensitive field
03Workflows
@sntxrr/gitlab-token-rotation
Keep one GitLab access token ahead of its own expiry: check what it has left every day, and rotate it only when a human has said to and it is actually close to lapsing. The default posture is deliberate. `rotate` defaults to FALSE, so the scheduled run is a read-only check that keeps the token's `daysRemaining` current and does nothing else. Rotation is irreversible the instant it lands — GitLab revokes the outgoing value immediately, and replaying it trips reuse detection which revokes the whol
checkRead the managed token's current expiry
1.sync-tokengitlab-token.sync— Read-only. Writes a `token` snapshot carrying `daysRemaining`, keyed by the token's real GitLab ID, which the rotate step below reads back through `data.findBySpec`.
rotateRotate, but only when told to and only when close to expiry
1.rotate-tokengitlab-token.rotate— Gated on BOTH `inputs.rotate` and the days-remaining threshold, in the model's own `when` argument. A false predicate costs nothing: the model returns before it touches the API and writes no resource, so the existing snapshot stays true rather than gaining a generation that was never issued.
`data.findBySpec` rather than `data.latest`: this model keys each snapshot by the token's real GitLab ID — deliberately, so drift reconciles and a rotated-away generation is not overwritten by its successor
04Previous Versions
2026.08.19.1
05Stats
A
100 / 100
Downloads
0
Archive size
24.8 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
06Platforms
07Labels