gitlab

Documentation

Overview

Package gitlab is the GitLab credential provider: personal access tokens and the other token families GitLab prefixes with `gl`: deploy, runner, CI job, pipeline trigger, feed, incoming mail, agent, OAuth application and feature flag tokens.

A routable personal access token, the format GitLab issues since 2025, carries a CRC32 checksum that is verified offline and a payload that names the organization, group, project or user it belongs to, which patty reads without contacting anyone. Every other family is matched on prefix, alphabet and length. A token is accepted by one GitLab instance it does not name, so verification asks gitlab.com, the instances the operator passed with --gitlab-url or GITLAB_URL, and the ones the scanned repository names. A personal access token revokes itself; the other families are revoked by their owner, and the report says where.

Index

• Constants
• func RoutableChecksum(encoded string) string
• func RoutableLength(n int) string
• type Provider
  • func New() *Provider
  • func (p *Provider) AllowPrivateServers(allow bool)
  • func (*Provider) Bind(tok detect.Token, instances []string) detect.Token
  • func (p *Provider) Configure(env func(string) string)
  • func (p *Provider) DryRunRevoke(ctx context.Context, tok detect.Token) error
  • func (*Provider) Find(content []byte) []detect.Token
  • func (*Provider) Instances(content []byte) []string
  • func (*Provider) Kinds() []detect.KindInfo
  • func (*Provider) LocalSources() detect.LocalSources
  • func (*Provider) Name() string
  • func (p *Provider) Revoke(ctx context.Context, tokens []detect.Token) error
  • func (p *Provider) Verify(ctx context.Context, tok detect.Token) detect.Verification

Constants

const (
	// URLEnv is the environment variable Configure reads Configured from:
	// one or more instance URLs separated by commas or whitespace.
	URLEnv = "GITLAB_URL"
	// URLFlag is the command line flag that adds instances to it.
	URLFlag = "--gitlab-url"
)

const (
	// KindPAT is a personal, project or group access token (glpat-).
	KindPAT detect.Kind = "gitlab-pat"
	// KindDeployToken is a deploy token (gldt-).
	KindDeployToken detect.Kind = "gitlab-deploy-token"
	// KindRunnerToken is a runner authentication token (glrt-).
	KindRunnerToken detect.Kind = "gitlab-runner-token"
	// KindJobToken is a CI job token (glcbt-).
	KindJobToken detect.Kind = "gitlab-ci-job-token"
	// KindTriggerToken is a pipeline trigger token (glptt-).
	KindTriggerToken detect.Kind = "gitlab-pipeline-trigger-token"
	// KindFeedToken is a user's feed token (glft-).
	KindFeedToken detect.Kind = "gitlab-feed-token"
	// KindIncomingMailToken is a user's incoming email token (glimt-).
	KindIncomingMailToken detect.Kind = "gitlab-incoming-mail-token"
	// KindAgentToken is an agent for Kubernetes token (glagent-).
	KindAgentToken detect.Kind = "gitlab-agent-token"
	// KindOAuthAppSecret is an OAuth application secret (gloas-).
	KindOAuthAppSecret detect.Kind = "gitlab-oauth-app-secret"
	// KindFeatureFlagClientToken is a feature flag client token (glffct-).
	KindFeatureFlagClientToken detect.Kind = "gitlab-feature-flag-client-token"
	// KindSCIMToken is a group's SCIM token (glsoat-).
	KindSCIMToken detect.Kind = "gitlab-scim-token"
)

Functions

func RoutableChecksum

func RoutableChecksum(encoded string) string

RoutableChecksum computes the seven base36 digits GitLab appends to a routable token: the CRC32 (IEEE) of everything before them. Exported so callers and tests can construct well-formed tokens without hard-coding any.

func RoutableLength

func RoutableLength(n int) string

RoutableLength renders a base64 payload's length the way the token carries it.

Types

type Provider

type Provider struct {
	// DefaultURL is the instance every token is tried against first,
	// https://gitlab.com by default.
	DefaultURL string
	Client     *http.Client
	// Configured are the instances the operator named with --gitlab-url or
	// GITLAB_URL. Configure reads the variable; the flag is added to it by
	// the command. They are contacted as given, plain http included:
	// naming one is the operator's decision.
	Configured []string
	// Policy decides which instances discovered in scanned content may be
	// contacted.
	Policy detect.ServerPolicy
}

Provider implements detect.Provider, detect.Revoker, detect.DryRunRevoker, detect.Configurable, detect.ServerVerifier and detect.InstanceObserver for GitLab.

func New

func New() *Provider

New returns a Provider against gitlab.com, with no other instance configured.

func (*Provider) AllowPrivateServers

func (p *Provider) AllowPrivateServers(allow bool)

AllowPrivateServers implements detect.ServerVerifier.

func (*Provider) Bind

func (*Provider) Bind(tok detect.Token, instances []string) detect.Token

Bind implements detect.InstanceObserver: the instances go into the token's companion material, next to the deploy username when there is one, for Verify to try.

func (*Provider) Configure

func (p *Provider) Configure(env func(string) string)

Configure implements detect.Configurable: the self-managed instances to verify tokens against come from GITLAB_URL.

func (*Provider) DryRunRevoke

func (p *Provider) DryRunRevoke(ctx context.Context, tok detect.Token) error

DryRunRevoke implements detect.DryRunRevoker: it authenticates with the token on the candidate instances, exactly what Revoke does before deleting, and stops there.

func (*Provider) Find

func (*Provider) Find(content []byte) []detect.Token

Find implements detect.Provider. One substring pass for the shared `gl` stem, then the family's exact shape at each candidate: the routable layout with its checksum for personal access and runner tokens, a fixed body in the token alphabet for most families, forty hex characters for a trigger token, a partition and a body for a job token. A deploy token is paired with the deploy username written in the same object.

func (*Provider) Instances

func (*Provider) Instances(content []byte) []string

Instances implements detect.InstanceObserver: every host with a `gitlab` label in content, the way a self-managed GitLab is usually named (gitlab.example.com), as it was written, with its scheme and port. gitlab.com is tried anyway, and its subdomains, gitlab.io and a GitHub Pages site are the vendor's own sites, not an instance.

func (*Provider) Kinds

func (*Provider) Kinds() []detect.KindInfo

Kinds implements detect.Provider. Only a personal access token revokes itself; every other family carries the owner's procedure.

func (*Provider) LocalSources

func (*Provider) LocalSources() detect.LocalSources

LocalSources implements detect.Provider: the glab CLI's configuration, the environment variables glab, python-gitlab, Terraform and GitLab CI read, and git's credential stores, whose entries for a GitLab host hold a token as the password.

func (*Provider) Name

func (*Provider) Name() string

Name implements detect.Provider.

func (*Provider) Revoke

func (p *Provider) Revoke(ctx context.Context, tokens []detect.Token) error

Revoke implements detect.Revoker for personal access tokens through DELETE /personal_access_tokens/self, authenticated with the token itself, on the first candidate instance that accepts it: the token does not say which GitLab issued it, so an instance that answers 401 is not the one and the next is tried. A 204 means the token is revoked; the caller confirms with Verify. No other family revokes itself.

func (*Provider) Verify

func (p *Provider) Verify(ctx context.Context, tok detect.Token) detect.Verification

Verify implements detect.Provider. A personal access token is tried against every candidate instance with GET /personal_access_tokens/self, a runner token with POST /runners/verify, a deploy token, together with its username, against the registry's token endpoint: gitlab.com and the instances the operator named, as given, then the ones the scanned repository named, subject to the server policy. The first instance that accepts it settles it; it is revoked only when every instance rejected it. Every other family has nobody to ask.