livery.forge._gitlab¶
livery.forge._gitlab ¶
The GitLab backend: livery.forge.Forge over REST v4.
The odd one out, and the reason several protocol rules exist: merge
requests and issues are addressed by their per-project iid (which is
the number a person sees, so the protocol's number is the iid and the
global id never crosses the boundary), pipelines are the canonical CI
answer rather than commit statuses, and the owner may be a group or
subgroup path. The full endpoint mapping is the package's
docs/gitlab.md.
Construction and the token rule: livery.forge.GitlabForge.connect
resolves the server once, an explicit url beating the configured
GITLAB_URL, and reads GITLAB_TOKEN, then the token glab
holds for the host, unless a token is passed.
The token belongs to the configured host and no other.
Capabilities: auto_merge (merge when pipeline succeeds),
ci_secrets (masked variables), and schedule_events
(reconstructed from system notes and state events) are supported;
min_approvals is probed per instance, because GitLab
licence-gates approval rules. force_cancel and
required_contexts are declined by name: pipelines have plain
cancel only, and no tier's protection names required check contexts.
Classes:
| Name | Description |
|---|---|
GitlabForge |
One GitLab server, spoken to through livery.forge.Forge's verbs. |
Functions:
| Name | Description |
|---|---|
gitlab_configured_host |
The host |
gitlab_is_configured_host |
Whether host is the server this environment holds a token for. |
GitlabForge ¶
One GitLab server, spoken to through livery.forge.Forge's verbs.
Build with livery.forge.GitlabForge.connect; the constructor takes the resolved values and applies no environment fallbacks.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
api_base
|
str
|
The API root, |
required |
token
|
str
|
The token sent on every request; empty reads anonymously. |
required |
opener
|
Opener | None
|
The network seam; the redirect-refusing default when omitted. |
None
|
Bind the client to api_base with token.
The timeout is generous: a single-node GitLab under load legitimately takes tens of seconds for its heaviest writes (project creation), and "slow" must stay distinguishable from "unreachable".
Methods:
| Name | Description |
|---|---|
connect |
The server, resolved once, never inferred from ambient state. |
whoami |
The authenticated user's login name ( |
server_version |
The server's version string ( |
registry_url |
Decline every kind, each naming its reason. |
supports |
Honest per instance: approvals depend on the licence. |
repository |
The view onto one repository. Cheap, no network. |
members |
The group's member usernames; a user namespace is its login. |
teams |
GitLab's teams are its subgroups: their full paths. |
codeowners |
GitLab's dialect: |
user_url |
The address of login's profile; nothing on the wire. |
create_repo |
Create the project under a group path or the token's own user. |
get_repo |
The project's settings, or None when it does not exist. |
delete_repo |
Delete the project; one already gone is success. |
Attributes:
| Name | Type | Description |
|---|---|---|
token |
str
|
The credential this connection authenticates with; empty when anonymous. |
Source code in packages/forge/src/livery/forge/_gitlab.py
token
property
¶
token: str
The credential this connection authenticates with; empty when anonymous.
connect
classmethod
¶
connect(*, url: str = '', token: str | None = None, opener: Opener | None = None) -> GitlabForge
The server, resolved once, never inferred from ambient state.
An explicit url wins; GITLAB_URL is the configured
default. token resolves as GITLAB_TOKEN first, then the
token glab holds for the server's host (glab config get
token --host); nothing found raises rather than silently
reading anonymously. Pass token="" to read anonymously on
purpose.
Source code in packages/forge/src/livery/forge/_gitlab.py
registry_url ¶
registry_url(kind: RegistryKind, owner: str) -> str
Decline every kind, each naming its reason.
GitLab's python and conan registries are addressed by project id, not by owner and name, and its container registry lives on a per-install host the API base does not reveal; the contract's declaration is the path on GitLab until a project-resolved surface earns its keep.
Source code in packages/forge/src/livery/forge/_gitlab.py
supports ¶
supports(capability: Capability) -> bool
Honest per instance: approvals depend on the licence.
auto_merge, ci_secrets, and schedule_events are
every tier's. min_approvals is probed once per connection
and cached: GitLab licence-gates approval rules, so the first
ask reads a visible project's approval-rules endpoint, which
an unlicensed server answers with 404. force_cancel and
required_contexts are declined at every tier: no tier
cancels a run harder than plain cancel, and no tier's
protection names check contexts.
Source code in packages/forge/src/livery/forge/_gitlab.py
repository ¶
repository(owner: str, name: str) -> Repository
members ¶
The group's member usernames; a user namespace is its login.
Source code in packages/forge/src/livery/forge/_gitlab.py
teams ¶
GitLab's teams are its subgroups: their full paths.
A personal namespace has no subgroups and answers empty.
Source code in packages/forge/src/livery/forge/_gitlab.py
codeowners ¶
codeowners(entries: tuple[CodeownersEntry, ...]) -> Codeowners
GitLab's dialect: .gitlab/CODEOWNERS with sections.
A section headed [name][n] carries the per-path approval
count in the file itself, the one dialect that can; nothing
is approximated. Every entry after a heading belongs to that
section until the next one, so the plain entries render
first and each counted entry gets its own section after
them: order in the input can never leak a count onto a
neighbour. Enforcing the counts still needs a paid tier,
which the min_approvals capability declines.
Source code in packages/forge/src/livery/forge/_gitlab.py
user_url ¶
create_repo ¶
create_repo(owner: str, name: str, *, private: bool = True, description: str = '') -> Repository
Create the project under a group path or the token's own user.
initialize_with_readme gives it the default branch the
protocol requires. A group or subgroup owner resolves to its
namespace id first. GitLab protects a new project's default
branch on creation (the instance or group default, maintainers
push and no force push); that rule is removed, so the creator
can push its history over the init commit, as on every other
forge, and protection starts when the caller configures it.
Source code in packages/forge/src/livery/forge/_gitlab.py
get_repo ¶
The project's settings, or None when it does not exist.
A deleting project is renamed to a corpse path and the old path answers as moved for a moment; a redirect here therefore means "no project at this path" and reads as None, never followed.
Source code in packages/forge/src/livery/forge/_gitlab.py
delete_repo ¶
Delete the project; one already gone is success.
GitLab deletes asynchronously: the project is renamed to a corpse path, the old path answers 405 ("Non GET methods are not allowed for moved projects") until the rename lands, and the path can stay reserved for a short while after. The 405 on a moved project IS the already-deleting case, so it reads as success; a creator reusing a just-deleted path retries on the refusal.
Source code in packages/forge/src/livery/forge/_gitlab.py
gitlab_configured_host ¶
gitlab_configured_host() -> str
The host GITLAB_TOKEN belongs to, from GITLAB_URL, lowercased.
gitlab_is_configured_host ¶
Whether host is the server this environment holds a token for.