Documentation
¶
Overview ¶
Package gitlab implements the gitlab source plugin: lists projects ("repositories") and members under a single GitLab group and emits the cross-vendor git_repository and directory_user evidence types — suitable for SOC 2 / ISO 27001 branch-protection, code-review, and identity (MFA/admin/lifecycle) policies.
GitLab is one of several substitutable source-code platforms (GitHub, Bitbucket, future Gitea/Azure DevOps); a policy accepts the git_repository evidence type, not a vendor, so this plugin is immediately usable by every policy that already consumes GitHub repositories (the substitutability principle — docs/architecture/04a-evidence-type-registry.md).
Per the KISS-no-DRY axiom (docs/architecture/04-source-plugins.md §The plugin contract), the plugin caches nothing across Collect calls. N policies bound to this plugin → N invocations of Collect.
Test injection: the API interface mirrors the github plugin — the concrete *sdkAPI (backed by gitlab.com/gitlab-org/api/client-go) satisfies it, and unit tests inject an in-memory fake. The real SDK adapter is exercised by an httptest-backed test; live integration tests against gitlab.com are deferred to the testing revamp.
directory_user (WU-2.2): the plugin also lists the group's members and emits one directory_user per member, mapping AccessLevel ≥ Maintainer (or instance-admin) → is_admin, account state → is_active, and the user's two_factor_enabled → mfa_enabled. 2FA and instance-admin status are only readable with a group-owner / instance-admin token (via the Users API); without that privilege the sdkAPI degrades gracefully and mfa_enabled is best-effort false — documented in docs/configuration.md.
Index ¶
Constants ¶
const EvidenceTypeDirectoryUser = "directory_user"
EvidenceTypeDirectoryUser is the cross-vendor directory_user shape this plugin emits for the group's members — identical to the shape the github and okta plugins emit (the same identity evidence type).
const EvidenceTypeRepository = "git_repository"
EvidenceTypeRepository is the cross-vendor git_repository shape this plugin emits.
const SourceID = "gitlab"
SourceID is the registered ID for the gitlab plugin instance.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type API ¶
type API interface {
// ListRepos returns all projects under the configured group,
// normalized into the git_repository contract. Implementations must
// page transparently — callers receive the full list in one slice.
ListRepos(ctx context.Context) ([]Repo, error)
// ListMembers returns all members of the configured group, normalized
// into the directory_user contract. Implementations must page
// transparently — callers receive the full list in one slice.
ListMembers(ctx context.Context) ([]Member, error)
}
API is the subset of the GitLab REST API the plugin uses. Defining it as an interface lets tests inject a fake without making real network calls; the concrete *sdkAPI satisfies it.
type Member ¶ added in v0.39.0
type Member struct {
Username string
Name string
Email string
MFAEnabled bool
IsAdmin bool
IsActive bool
}
Member is the subset of fields the plugin extracts from a GitLab group member, normalized into the directory_user contract. Every field maps to a property the consuming policies read so none reads an absent field.
MFAEnabled and the instance-admin component of IsAdmin require a group-owner / instance-admin token (the Users API exposes two_factor_enabled / is_admin); the sdkAPI degrades gracefully when the token can't read them, leaving MFAEnabled best-effort false.
type Options ¶
type Options struct {
API API
// Now is injected so tests can produce deterministic CollectedAt
// values. Production callers leave it nil → time.Now().UTC().
Now func() time.Time
}
Options is the constructor input.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is the in-process gitlab source.
func New ¶
New constructs a Plugin around an explicit API implementation. Callers using the real GitLab REST API should use NewFromToken.
func NewFromToken ¶
NewFromToken constructs a Plugin backed by the real GitLab REST API for the given group, using the supplied personal-access/group token. A blank baseURL defaults to gitlab.com; self-managed instances pass their own URL. Live integration tests are deferred.
func (*Plugin) Collect ¶
func (p *Plugin) Collect(ctx context.Context, req core.SlotRequest) ([]core.EvidenceRecord, error)
Collect dispatches to the per-type collectors for whichever emitted types the slot accepts, returning their records together. A slot that accepts neither emitted type is rejected.
type Repo ¶
type Repo struct {
Name string
DefaultBranch string
ProtectionOn bool
RequiredReviews int
RequiresSignedCommits bool
RequiresLinearHistory bool
AllowsForcePush bool
DismissStaleReviews bool
RequireCodeOwnerReviews bool
IsPrivate bool
Archived bool
SecretScanningEnabled bool
PushProtectionEnabled bool
DependabotAlertsEnabled bool
CodeScanningEnabled bool
}
Repo is the subset of fields the plugin extracts from a GitLab project, normalized into the git_repository contract. Every field maps to a property of the git_repository evidence type so policies never read an absent field.
Fields without a read-only GitLab API analog are left at their zero value and documented at the mapping site (sdkAPI.ListRepos):
- SecretScanningEnabled / CodeScanningEnabled / DependabotAlertsEnabled (GitLab pipeline SAST/Secret/Dependency scanning is configured in .gitlab-ci.yml, not exposed as a project-settings boolean).
Source Files