Documentation
¶
Overview ¶
Package branchrules implements MCP tools for GitLab branch rule discovery.
The package wraps GitLab GraphQL branch rule fields:
Index ¶
- func ActionSpecs(client *gitlabclient.Client) []toolutil.ActionSpec
- func FormatListMarkdown(out ListOutput) string
- type Access
- type AccessDeployKey
- type AccessGroup
- type ApprovalRule
- type BranchProtection
- type BranchRuleItem
- type ExternalStatusCheck
- type ListInput
- type ListOutput
- type PushAccess
- type UserRef
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ActionSpecs ¶
func ActionSpecs(client *gitlabclient.Client) []toolutil.ActionSpec
ActionSpecs returns canonical specs for branch rule actions.
func FormatListMarkdown ¶
func FormatListMarkdown(out ListOutput) string
FormatListMarkdown renders a page of branch rules as a Markdown table, followed by one section per rule that carries grants, settings, approval rules or external status checks.
Types ¶
type Access ¶ added in v3.1.0
type Access struct {
AccessLevel int `json:"access_level"`
AccessLevelDescription string `json:"access_level_description"`
User *UserRef `json:"user,omitempty" tier:"premium"`
Group *AccessGroup `json:"group,omitempty" tier:"premium"`
}
Access is one grant on a protected branch: a role, and on Premium and above a specific user or group, allowed to merge into, push to or unprotect the branches the rule matches. The description is GitLab's own reading of the grant: the role's name, or the user's or the group's.
type AccessDeployKey ¶ added in v3.1.0
type AccessDeployKey struct {
ID string `json:"id"`
Title string `json:"title"`
ExpiresAt string `json:"expires_at,omitempty"`
User UserRef `json:"user"`
}
AccessDeployKey is the deploy key a push grant names, with the user it is assigned to.
type AccessGroup ¶ added in v3.1.0
type AccessGroup struct {
ID string `json:"id"`
Name string `json:"name"`
WebURL string `json:"web_url"`
AvatarURL string `json:"avatar_url,omitempty"`
}
AccessGroup identifies a group a grant names. Its parent is not selected: the chain is recursive, so a document could only select it to a depth fixed in advance, and the group's web URL already spells its whole path.
type ApprovalRule ¶
type ApprovalRule struct {
ID string `json:"id"`
Name string `json:"name"`
ApprovalsRequired int `json:"approvals_required"`
Type string `json:"type,omitempty"`
EligibleApprovers []UserRef `json:"eligible_approvers,omitempty"`
}
ApprovalRule represents an approval rule associated with a branch rule.
type BranchProtection ¶
type BranchProtection struct {
AllowForcePush bool `json:"allow_force_push"`
CodeOwnerApprovalRequired *bool `json:"code_owner_approval_required,omitempty" tier:"premium"`
ModificationBlockedByPolicy *bool `json:"modification_blocked_by_policy,omitempty" tier:"ultimate"`
ProtectedFromPushBySecurityPolicy *bool `json:"protected_from_push_by_security_policy,omitempty" tier:"ultimate"`
WarnModificationBlockedByPolicy *bool `json:"warn_modification_blocked_by_policy,omitempty" tier:"ultimate"`
WarnProtectedFromPushBySecurityPolicy *bool `json:"warn_protected_from_push_by_security_policy,omitempty" tier:"ultimate"`
PushAccessLevels []PushAccess `json:"push_access_levels,omitempty"`
MergeAccessLevels []Access `json:"merge_access_levels,omitempty"`
UnprotectAccessLevels []Access `json:"unprotect_access_levels,omitempty" tier:"premium"`
}
BranchProtection holds protection settings for a branch rule: who may push, merge and unprotect, and the flags that decide what a push may do. The four security-policy flags are absent rather than false on a release older than 18.8, which is not asked about them (see List).
type BranchRuleItem ¶
type BranchRuleItem struct {
ID string `json:"id,omitempty"`
Name string `json:"name"`
IsDefault bool `json:"is_default"`
IsProtected bool `json:"is_protected"`
MatchingBranchesCount int `json:"matching_branches_count"`
CreatedAt string `json:"created_at,omitempty"`
UpdatedAt string `json:"updated_at,omitempty"`
BranchProtection *BranchProtection `json:"branch_protection,omitempty"`
ApprovalRules []ApprovalRule `json:"approval_rules,omitempty" tier:"premium"`
ExternalStatusChecks []ExternalStatusCheck `json:"external_status_checks,omitempty" tier:"ultimate"`
}
BranchRuleItem represents a branch rule summary.
A field the Community document cannot select is a pointer or a slice that stays empty on a Community instance, so a caller told nothing about code owners reads the field as absent rather than as false. The tier tags name the licensed feature each field reports on; GitLab's schema declares none, so they come from the feature table the GitLab release licenses (ee/app/models/gitlab_subscriptions/features.rb).
type ExternalStatusCheck ¶
type ExternalStatusCheck struct {
ID string `json:"id"`
Name string `json:"name"`
ExternalURL string `json:"external_url"`
HMAC *bool `json:"hmac,omitempty"`
}
ExternalStatusCheck represents an external status check on a branch rule. Whether an HMAC secret signs its requests is absent rather than false on a release older than 18.8, which is not asked (see List).
type ListInput ¶
type ListInput struct {
ProjectPath string `json:"project_path" jsonschema:"required,Project full path (e.g. my-group/my-project)"`
toolutil.GraphQLPaginationInput
}
ListInput is the input for listing branch rules.
type ListOutput ¶
type ListOutput struct {
toolutil.HintableOutput
Rules []BranchRuleItem `json:"rules"`
Pagination toolutil.GraphQLForwardPaginationOutput `json:"pagination"`
}
ListOutput is the output for listing branch rules.
Pagination is forward-only because Project.branchRules is: it accepts first and after alone, and reports neither a previous page nor a start cursor.
func List ¶
func List(ctx context.Context, client *gitlabclient.Client, input ListInput) (ListOutput, error)
List retrieves branch rules for a project via the GitLab GraphQL API. It selects the EE query (with approval rules, external status checks, and code owner approval) when the client is configured for Enterprise, otherwise it uses the CE-compatible query that omits EE-only fields.
A licensed instance is sent the 18.8 Enterprise document first, and the base one when it refuses a field the first names: that is how a release from 16.11 to 18.7 answers, and it answers before running anything, so a retry repeats no work GitLab did. Holding every licensed instance to the base document instead would leave the four security-policy flags and a status check's hmac unread on every release that serves them, and holding it to the 18.8 one alone would refuse the whole listing, grants included, below 18.8. A refusal of any other kind is reported as it is.
type PushAccess ¶ added in v3.1.0
type PushAccess struct {
Access
DeployKey *AccessDeployKey `json:"deploy_key,omitempty"`
}
PushAccess is a push grant, the one kind that may name a deploy key.
type UserRef ¶ added in v3.1.0
type UserRef struct {
ID string `json:"id"`
Username string `json:"username"`
Name string `json:"name"`
PublicEmail string `json:"public_email,omitempty"`
AvatarURL string `json:"avatar_url,omitempty"`
WebURL string `json:"web_url"`
WebPath string `json:"web_path"`
}
UserRef identifies a user a grant, a deploy key or an approval rule names. The id is the user's numeric id as a string wherever the user appears: a grant's user and a deploy key's user carry it bare, and an eligible approver, which GitLab identifies by a global ID (gid://gitlab/User/21), is read back to the same number, so one user matches itself across the response.
Source Files