gitlabapp package - github.com/GLINCKER/levelrail/internal/gitlabapp

Documentation ¶

Overview ¶

Package gitlabapp implements OAuth2 and the small slice of GitLab's REST API this control plane needs once connected.

Methods take instanceURL explicitly rather than baking one into the Client, since GitLab is commonly self-hosted and not fixed like api.github.com.

Index ¶

Constants
Variables
func AuthorizeURL(instanceURL, clientID, redirectURI, state string) string
type Account
type Branch
type Client
- func NewClient() *Client
type CommitState
type CommitStatus
type Project
type TokenInfo
type Tokens

Constants ¶

View Source

const DefaultScope = "api"

DefaultScope requests read access for project listing and write access for registering a project webhook: GitLab's own docs (docs.gitlab.com/ee/api/oauth2.html) document "api" as required for the webhook-creation endpoint, "read_api" alone is not enough.

Variables ¶

View Source

var ErrTooManyStatuses = errors.New("gitlabapp: commit has too many statuses to read")

ErrTooManyStatuses means the commit has more statuses than one read walks.

Functions ¶

func AuthorizeURL ¶

func AuthorizeURL(instanceURL, clientID, redirectURI, state string) string

AuthorizeURL builds the GitLab OAuth2 authorization-code flow's entry point: a real browser redirect (GET), not a fetch call, the same "the operator's browser must navigate here itself" shape internal/githubapp's manifest flow requires for the equivalent reason.

Types ¶

type Account ¶

type Account struct {
	ID    string
	Login string
}

Account is the authenticated user behind an access token.

type Branch ¶

type Branch struct {
	Name      string
	CommitSHA string
}

Branch is one branch of one project.

type Client ¶

type Client struct {
	HTTP *http.Client
}

Client is a small, purpose-built GitLab REST/OAuth client, not a general-purpose GitLab SDK.

func NewClient ¶

func NewClient() *Client

NewClient returns a Client with a bounded per-request timeout, the same reasoning internal/githubapp.NewClient's own doc comment gives.

func (*Client) CompareChangedFiles ¶ added in v0.2.0

func (c *Client) CompareChangedFiles(ctx context.Context, instanceURL, accessToken, projectPath, from, to string) ([]string, error)

CompareChangedFiles lists the files that differ between from and to.

func (*Client) CreateCommitStatus ¶ added in v0.2.0

func (c *Client) CreateCommitStatus(ctx context.Context, instanceURL, accessToken, projectPath, sha string, state CommitState, targetURL, description, name string) error

CreateCommitStatus sets a commit status on sha of projectPath ("namespace/project"), authenticated with an OAuth access token the same way CreateProjectWebhook is. name is GitLab's own label to differentiate one status from another on the same commit (docs.gitlab.com/api/commits/#set-the-pipeline-status-of-a-commit), the same role GitHub's own "context" plays.

func (*Client) CreateMergeRequestNote ¶ added in v0.2.0

func (c *Client) CreateMergeRequestNote(ctx context.Context, instanceURL, accessToken, projectPath string, mrIID int, body string) (int64, error)

CreateMergeRequestNote posts a new note on merge request mrIID of projectPath ("namespace/project") and returns its ID.

func (*Client) CreateProjectWebhook ¶

func (c *Client) CreateProjectWebhook(ctx context.Context, instanceURL, accessToken string, projectID int64, hookURL, secretToken string) error

CreateProjectWebhook registers a push- and merge-request-events webhook on projectID pointed at hookURL, authenticated by GitLab's own X-Gitlab-Token scheme (secretToken echoed back on every delivery, not an HMAC signature the way GitHub's webhooks work). merge_requests_events must be requested explicitly: without it GitLab never sends the "Merge Request Hook" delivery internal/webhook's GitLab pull-request parsing expects, so preview environments would silently never trigger for a connected project.

func (*Client) CurrentUser ¶

func (c *Client) CurrentUser(ctx context.Context, instanceURL, accessToken string) (Account, error)

CurrentUser returns the user an access token belongs to.

func (*Client) ExchangeCode ¶

func (c *Client) ExchangeCode(ctx context.Context, instanceURL, clientID, clientSecret, redirectURI, code string) (Tokens, error)

ExchangeCode exchanges an OAuth authorization code for an access token, GitLab's documented POST {instance}/oauth/token grant_type "authorization_code" (docs.gitlab.com/ee/api/oauth2.html).

func (*Client) GetProject ¶

func (c *Client) GetProject(ctx context.Context, instanceURL, accessToken string, projectID int64) (Project, error)

GetProject looks up a single project by ID.

func (*Client) ListBranches ¶

func (c *Client) ListBranches(ctx context.Context, instanceURL, accessToken string, projectID int64) ([]Branch, error)

ListBranches lists every branch of projectID, across as many pages as GitLab returns full pages for, the same pagination shape ListProjects uses.

func (*Client) ListCommitStatuses ¶

func (c *Client) ListCommitStatuses(ctx context.Context, instanceURL, accessToken, projectPath, sha, ref string) ([]CommitStatus, error)

ListCommitStatuses returns the latest status per job name of sha in projectPath, read from the API for that exact commit. A non-empty ref limits the list to that branch or tag, so other pipelines on the SHA are ignored. Redirects are not followed, so the token only ever reaches instanceURL's own host.

func (*Client) ListMergeRequestNotes ¶ added in v0.2.0

func (c *Client) ListMergeRequestNotes(ctx context.Context, instanceURL, accessToken, projectPath string, mrIID int) ([]gitprovider.Comment, error)

ListMergeRequestNotes returns the oldest notes of merge request mrIID, up to gitprovider.MaxCommentPages pages.

func (*Client) ListProjects ¶

func (c *Client) ListProjects(ctx context.Context, instanceURL, accessToken string, opts gitprovider.ListOptions) ([]Project, gitprovider.ListResult, error)

ListProjects lists projects the token's account is at least a member of, page by page until GitLab runs out or the MaxItems cap is reached.

func (*Client) MergeRequestChangedFiles ¶ added in v0.2.0

func (c *Client) MergeRequestChangedFiles(ctx context.Context, instanceURL, accessToken, projectPath string, mrIID int) ([]string, error)

MergeRequestChangedFiles lists the files changed by merge request mrIID.

func (*Client) RefreshToken ¶

func (c *Client) RefreshToken(ctx context.Context, instanceURL, clientID, clientSecret, refreshToken string) (Tokens, error)

RefreshToken exchanges a still-valid refresh token for a new access token, GitLab's grant_type "refresh_token" on the same endpoint ExchangeCode uses.

func (*Client) RevokeToken ¶

func (c *Client) RevokeToken(ctx context.Context, instanceURL, clientID, clientSecret, token string) error

RevokeToken revokes an access or refresh token at the instance, ending the grant. GitLab answers 200 even for an already revoked token.

func (*Client) TokenInfo ¶

func (c *Client) TokenInfo(ctx context.Context, instanceURL, accessToken string) (TokenInfo, error)

TokenInfo reads the scopes of the token itself (GitLab 15.5 and newer).

func (*Client) UpdateMergeRequestNote ¶ added in v0.2.0

func (c *Client) UpdateMergeRequestNote(ctx context.Context, instanceURL, accessToken, projectPath string, mrIID int, noteID int64, body string) error

UpdateMergeRequestNote replaces the body of an existing note.

type CommitState ¶ added in v0.2.0

type CommitState string

CommitState is GitLab's own documented "state" enum for POST .../statuses/{sha}.

const (
	// CommitStateRunning marks a commit status as actively running.
	CommitStateRunning CommitState = "running"
	// CommitStateCanceled marks a commit status as canceled.
	CommitStateCanceled CommitState = "canceled"
)

Extra commit states used for pipeline run reporting.

const (
	// CommitStatePending marks a commit status as still in progress.
	CommitStatePending CommitState = "pending"
	// CommitStateSuccess marks a commit status as succeeded.
	CommitStateSuccess CommitState = "success"
	// CommitStateFailed marks a commit status as failed.
	CommitStateFailed CommitState = "failed"
)

type CommitStatus ¶

type CommitStatus struct {
	Name         string `json:"name"`
	Status       string `json:"status"`
	AllowFailure bool   `json:"allow_failure"`
}

CommitStatus is one job or external status on a commit. Status is GitLab's own value: created, pending, running, success, failed, canceled, skipped, manual and the like.

type Project ¶

type Project struct {
	ID                int64
	Name              string
	PathWithNamespace string
	HTTPURLToRepo     string
	DefaultBranch     string
	Visibility        string
	WebURL            string
	Archived          bool
	Fork              bool
}

Project is one GitLab project accessible to the connected account, the subset of GitLab's Project object this control plane's project picker and "use as source" action need.

type TokenInfo ¶

type TokenInfo struct {
	Name   string
	Scopes []string
}

TokenInfo is what GitLab reports about a personal, project or group access token.

type Tokens ¶

type Tokens struct {
	AccessToken  string
	RefreshToken string
	ExpiresAt    time.Time
}

Tokens is ExchangeCode's and RefreshToken's shared result.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL