gitlab

package
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 2, 2025 License: GPL-3.0 Imports: 25 Imported by: 0

Documentation

Overview

Package gitlab provides a wrapper around GitLab's APIs in a manner compliant with the forge.Forge interface.

Index

Constants

View Source 
const (
	// DefaultURL Default URLs for GitLab and its API.
	DefaultURL = "https://gitlab.com"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AuthType 

type AuthType int

AuthType specifies the kind of authentication method used. 

const (
	// AuthTypePAT states that PAT authentication was used.
	AuthTypePAT AuthType = iota

	// AuthTypeOAuth2 states that OAuth2 authentication was used.
	AuthTypeOAuth2

	// AuthTypeGitLabCLI states that GitLab CLI authentication was used.
	AuthTypeGitLabCLI

	// AuthTypeEnvironmentVariable states
	// that the token was set via an environment variable.
	//
	// This is not a real authentication method.
	AuthTypeEnvironmentVariable AuthType = 100
)

func (AuthType) MarshalText 

func (a AuthType) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (AuthType) String 

func (a AuthType) String() string

String returns the string representation of the AuthType.

func (*AuthType) UnmarshalText 

func (a *AuthType) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type AuthenticationToken 

type AuthenticationToken struct {
	forge.AuthenticationToken

	// AuthType specifies the kind of authentication method used.
	//
	// If AuthTypeGitLabCLI, AccessToken is not used.
	AuthType AuthType `json:"auth_type,omitempty"` // required

	// AccessToken is the GitLab access token.
	AccessToken string `json:"access_token,omitempty"`

	// Hostname is the hostname of the GitLab instance.
	//
	// Used only for AuthTypeGitLabCLI.
	Hostname string `json:"hostname,omitempty"`
}

AuthenticationToken defines the token returned by the GitLab forge.

type CLIAuthenticator 

type CLIAuthenticator struct {
	CLI      gitlabCLI // required
	Hostname string    // required
}

CLIAuthenticator implements GitLab CLI authentication flow. This doesn't do anything special besides checking if the user is logged in.

func (*CLIAuthenticator) Authenticate 

func (a *CLIAuthenticator) Authenticate(ctx context.Context, _ ui.View) (*AuthenticationToken, error)

Authenticate checks if the user is authenticated with GitHub CLI. The returned AuthenticationToken is saved to the stash.

type DeviceFlowAuthenticator 

type DeviceFlowAuthenticator struct {
	// Endpoint is the OAuth endpoint to use.
	Endpoint oauth2.Endpoint

	// ClientID for the OAuth or GitHub App.
	ClientID string

	// Scopes specifies the OAuth scopes to request.
	Scopes []string
}

DeviceFlowAuthenticator implements the OAuth device flow for GitHub. This is used for OAuth and GitHub App authentication.

func (*DeviceFlowAuthenticator) Authenticate 

func (a *DeviceFlowAuthenticator) Authenticate(ctx context.Context, view ui.View) (*AuthenticationToken, error)

Authenticate executes the OAuth authentication flow.

type Forge 

type Forge struct {
	Options Options

	// Log specifies the logger to use.
	Log *log.Logger
}

Forge builds a GitLab Forge.

func (*Forge) AuthenticationFlow 

func (f *Forge) AuthenticationFlow(ctx context.Context, view ui.View) (forge.AuthenticationToken, error)

AuthenticationFlow prompts the user to authenticate with GitLab. This rejects the request if the user is already authenticated with a GITLAB_TOKEN environment variable.

func (*Forge) CLIPlugin 

func (f *Forge) CLIPlugin() any

CLIPlugin returns the CLI plugin for the GitLab Forge.

func (*Forge) ChangeTemplatePaths 

func (f *Forge) ChangeTemplatePaths() []string

ChangeTemplatePaths reports the allowed paths for possible MR templates.

Ref https://docs.gitlab.com/ee/user/project/description_templates.html#create-a-merge-request-template.

func (*Forge) ClearAuthenticationToken 

func (f *Forge) ClearAuthenticationToken(stash secret.Stash) error

ClearAuthenticationToken removes the authentication token from the stash.

func (*Forge) ID 

func (*Forge) ID() string

ID reports a unique key for this forge.

func (*Forge) LoadAuthenticationToken 

func (f *Forge) LoadAuthenticationToken(stash secret.Stash) (forge.AuthenticationToken, error)

LoadAuthenticationToken loads the authentication token from the stash. If the user has set GITLAB_TOKEN, it will be used instead.

func (*Forge) MarshalChangeID added in v0.10.0 

func (*Forge) MarshalChangeID(id forge.ChangeID) (json.RawMessage, error)

MarshalChangeID serializes a MR into JSON.

func (*Forge) MarshalChangeMetadata 

func (*Forge) MarshalChangeMetadata(md forge.ChangeMetadata) (json.RawMessage, error)

MarshalChangeMetadata serializes a MRMetadata into JSON.

func (*Forge) MatchURL 

func (f *Forge) MatchURL(remoteURL string) bool

MatchURL reports whether the given URL is a GitLab URL.

func (*Forge) OpenURL 

func (f *Forge) OpenURL(ctx context.Context, token forge.AuthenticationToken, remoteURL string) (forge.Repository, error)

OpenURL opens a GitLab repository from a remote URL. Returns forge.ErrUnsupportedURL if the URL is not a valid GitLab URL.

func (*Forge) SaveAuthenticationToken 

func (f *Forge) SaveAuthenticationToken(stash secret.Stash, t forge.AuthenticationToken) error

SaveAuthenticationToken saves the given authentication token to the stash.

func (*Forge) URL 

func (f *Forge) URL() string

URL returns the base URL configured for the GitLab Forge or the default URL if none is set.

func (*Forge) UnmarshalChangeID added in v0.10.0 

func (*Forge) UnmarshalChangeID(data json.RawMessage) (forge.ChangeID, error)

UnmarshalChangeID deserializes a MR from JSON.

func (*Forge) UnmarshalChangeMetadata 

func (*Forge) UnmarshalChangeMetadata(data json.RawMessage) (forge.ChangeMetadata, error)

UnmarshalChangeMetadata deserializes a MRMetadata from JSON.

type MR 

type MR struct {
	// Number is the merge request number.
	// This will always be set.
	Number int `json:"number"` // required
}

MR uniquely identifies a Merge Request in GitLab. It's a valid forge.ChangeID.

func (*MR) String 

func (id *MR) String() string

func (*MR) UnmarshalJSON 

func (id *MR) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals a GitLab change ID. It accepts the following format: {"number": 123}

type MRComment 

type MRComment struct {
	// Number is the ID of the note.
	Number int `json:"number"` // required

	// MRNumber is the ID of the MR the note is on.
	MRNumber int `json:"mr_number"` // required
}

MRComment identifies a comment on a GitLab MR. These are referred to as "notes" in GitLab's API.

MRComment implements forge.ChangeCommentID.

func (*MRComment) String 

func (c *MRComment) String() string

type MRMetadata 

type MRMetadata struct {
	// MR is the merge request this metadata is for.
	MR *MR `json:"mr,omitempty"`

	// NavigationComment is the comment on the merge request
	// where we visualize the stack of MRs.
	NavigationComment *MRComment `json:"comment,omitempty"`
}

MRMetadata is the metadata for a merge request persisted in git-spice's data store.

func (*MRMetadata) ChangeID 

func (m *MRMetadata) ChangeID() forge.ChangeID

ChangeID reports the change ID of the pull request.

func (*MRMetadata) ForgeID 

func (*MRMetadata) ForgeID() string

ForgeID reports the forge ID that owns this metadata.

func (*MRMetadata) NavigationCommentID 

func (m *MRMetadata) NavigationCommentID() forge.ChangeCommentID

NavigationCommentID reports the comment ID of the navigation comment left on the merge request.

func (*MRMetadata) SetNavigationCommentID 

func (m *MRMetadata) SetNavigationCommentID(id forge.ChangeCommentID)

SetNavigationCommentID sets the comment ID of the navigation comment left on the merge request.

id may be nil.

type Options 

type Options struct {
	// URL is the URL for GitLab.
	// Override this for testing or if you use an on premise GitLab instance.
	URL string `name:"gitlab-url" hidden:"" config:"forge.gitlab.url" env:"GITLAB_URL" help:"Base URL for GitLab web requests"`

	// Token is a fixed token used to authenticate with GitLab.
	// This may be used to skip the login flow.
	Token string `name:"gitlab-token" hidden:"" env:"GITLAB_TOKEN" help:"GitLab API token"`

	// ClientID is the OAuth client ID for GitLab OAuth device flow.
	// This should be used if the GitLab instance is Self Managed.
	ClientID string `` /* 135-byte string literal not displayed */
}

Options defines command line options for the GitLab Forge. These are all hidden in the CLI, and are expected to be set only via environment variables.

type PATAuthenticator 

type PATAuthenticator struct{}

PATAuthenticator implements PAT authentication for GitLab.

func (*PATAuthenticator) Authenticate 

func (a *PATAuthenticator) Authenticate(ctx context.Context, view ui.View) (*AuthenticationToken, error)

Authenticate prompts the user for a Personal Access Token, validates it, and returns the token if successful.

type Repository 

type Repository struct {
	// contains filtered or unexported fields
}

Repository is a GitLab repository.

func (*Repository) ChangesAreMerged 

func (r *Repository) ChangesAreMerged(ctx context.Context, ids []forge.ChangeID) ([]bool, error)

ChangesAreMerged reports whether the given changes have been merged.

func (*Repository) DeleteChangeComment 

func (r *Repository) DeleteChangeComment(
	ctx context.Context,
	id forge.ChangeCommentID,
) error

DeleteChangeComment deletes an existing comment on a PR.

func (*Repository) EditChange 

func (r *Repository) EditChange(ctx context.Context, id forge.ChangeID, opts forge.EditChangeOptions) error

EditChange edits an existing change in a repository.

func (*Repository) FindChangeByID 

func (r *Repository) FindChangeByID(ctx context.Context, id forge.ChangeID) (*forge.FindChangeItem, error)

FindChangeByID searches for a change with the given ID.

func (*Repository) FindChangesByBranch 

func (r *Repository) FindChangesByBranch(ctx context.Context, branch string, opts forge.FindChangesOptions) ([]*forge.FindChangeItem, error)

FindChangesByBranch searches for changes with the given branch name. It returns both open and closed changes. Only recent changes are returned, limited by the given limit.

func (*Repository) Forge 

func (r *Repository) Forge() forge.Forge

Forge returns the forge this repository belongs to.

func (*Repository) ListChangeComments 

func (r *Repository) ListChangeComments(
	ctx context.Context,
	id forge.ChangeID,
	options *forge.ListChangeCommentsOptions,
) iter.Seq2[*forge.ListChangeCommentItem, error]

ListChangeComments lists comments on an MR, optionally applying the given filtering options.

func (*Repository) ListChangeTemplates 

func (r *Repository) ListChangeTemplates(ctx context.Context) ([]*forge.ChangeTemplate, error)

ListChangeTemplates returns MR templates defined in the repository.

func (*Repository) NewChangeMetadata 

func (r *Repository) NewChangeMetadata(_ context.Context, id forge.ChangeID) (forge.ChangeMetadata, error)

NewChangeMetadata returns the metadata for a merge request.

func (*Repository) PostChangeComment 

func (r *Repository) PostChangeComment(
	ctx context.Context,
	id forge.ChangeID,
	markdown string,
) (forge.ChangeCommentID, error)

PostChangeComment posts a new comment on an MR.

func (*Repository) SubmitChange 

func (r *Repository) SubmitChange(ctx context.Context, req forge.SubmitChangeRequest) (forge.SubmitChangeResult, error)

SubmitChange creates a new change in a repository.

func (*Repository) UpdateChangeComment 

func (r *Repository) UpdateChangeComment(
	ctx context.Context,
	id forge.ChangeCommentID,
	markdown string,
) error

UpdateChangeComment updates the contents of an existing comment on an MR.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.