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, codeChallenge string) string
- type Account
- type Branch
- type Client
- func (c *Client) CompareChangedFiles(ctx context.Context, instanceURL, accessToken, projectPath, from, to string) ([]string, error)
- func (c *Client) CreateCommitStatus(ctx context.Context, instanceURL, accessToken, projectPath, sha string, ...) error
- func (c *Client) CreateDeployment(ctx context.Context, ...) (int64, error)
- func (c *Client) CreateMergeRequestNote(ctx context.Context, instanceURL, accessToken, projectPath string, mrIID int, ...) (int64, error)
- func (c *Client) CreateProjectWebhook(ctx context.Context, instanceURL, accessToken string, projectID int64, ...) error
- func (c *Client) CurrentUser(ctx context.Context, instanceURL, accessToken string) (Account, error)
- func (c *Client) EnsureEnvironment(ctx context.Context, ...) (Environment, error)
- func (c *Client) ExchangeCode(ctx context.Context, ...) (Tokens, error)
- func (c *Client) FindEnvironment(ctx context.Context, instanceURL, accessToken, projectPath, name string) (Environment, bool, error)
- func (c *Client) GetProject(ctx context.Context, instanceURL, accessToken string, projectID int64) (Project, error)
- func (c *Client) ListBranches(ctx context.Context, instanceURL, accessToken string, projectID int64) ([]Branch, error)
- func (c *Client) ListCommitStatuses(ctx context.Context, instanceURL, accessToken, projectPath, sha, ref string) ([]CommitStatus, error)
- func (c *Client) ListGroups(ctx context.Context, instanceURL, accessToken string, limit int) (paths []string, more bool, err error)
- func (c *Client) ListMergeRequestNotes(ctx context.Context, instanceURL, accessToken, projectPath string, mrIID int) ([]gitprovider.Comment, error)
- func (c *Client) ListProjects(ctx context.Context, instanceURL, accessToken string, ...) ([]Project, gitprovider.ListResult, error)
- func (c *Client) MergeRequestChangedFiles(ctx context.Context, instanceURL, accessToken, projectPath string, mrIID int) ([]string, error)
- func (c *Client) OAuthTokenInfo(ctx context.Context, instanceURL, accessToken string) (TokenInfo, error)
- func (c *Client) RefreshToken(ctx context.Context, instanceURL, clientID, clientSecret, refreshToken string) (Tokens, error)
- func (c *Client) RevokeToken(ctx context.Context, instanceURL, clientID, clientSecret, token string) error
- func (c *Client) RotateSelf(ctx context.Context, instanceURL, accessToken string, expiresAt time.Time) (token, newExpiry string, err error)
- func (c *Client) SetEnvironmentURL(ctx context.Context, instanceURL, accessToken, projectPath string, envID int64, ...) error
- func (c *Client) StopEnvironment(ctx context.Context, instanceURL, accessToken, projectPath, name string) error
- func (c *Client) TokenInfo(ctx context.Context, instanceURL, accessToken string) (TokenInfo, error)
- func (c *Client) UpdateDeploymentStatus(ctx context.Context, instanceURL, accessToken, projectPath string, id int64, ...) error
- func (c *Client) UpdateMergeRequestNote(ctx context.Context, instanceURL, accessToken, projectPath string, mrIID int, ...) error
- type CommitState
- type CommitStatus
- type DeploymentStatus
- type Environment
- type Project
- type TokenInfo
- type Tokens
Constants ¶
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 ¶
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 ¶
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 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) CreateDeployment ¶
func (c *Client) CreateDeployment(ctx context.Context, instanceURL, accessToken, projectPath, environment, sha, ref string, tag bool, status DeploymentStatus) (int64, error)
CreateDeployment records a deployment of sha to the named environment and returns its ID. ref is the branch or tag the commit was deployed from.
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 ¶
CurrentUser returns the user an access token belongs to.
func (*Client) EnsureEnvironment ¶
func (c *Client) EnsureEnvironment(ctx context.Context, instanceURL, accessToken, projectPath, name, externalURL, tier string) (Environment, error)
EnsureEnvironment returns the environment called name, creating it when it is missing. A repeat call is a no-op, and a lost create race falls back to the environment that won.
func (*Client) ExchangeCode ¶
func (c *Client) ExchangeCode(ctx context.Context, instanceURL, clientID, clientSecret, redirectURI, code, codeVerifier 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) FindEnvironment ¶
func (c *Client) FindEnvironment(ctx context.Context, instanceURL, accessToken, projectPath, name string) (Environment, bool, error)
FindEnvironment returns the environment called name, or ok=false when the project has none.
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) ListGroups ¶
func (c *Client) ListGroups(ctx context.Context, instanceURL, accessToken string, limit int) (paths []string, more bool, err error)
ListGroups returns the full paths of up to limit groups the token's user belongs to. more is true when GitLab holds further groups past the limit.
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) OAuthTokenInfo ¶
func (c *Client) OAuthTokenInfo(ctx context.Context, instanceURL, accessToken string) (TokenInfo, error)
OAuthTokenInfo reads the scopes and lifetime of an OAuth access token.
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) RotateSelf ¶
func (c *Client) RotateSelf(ctx context.Context, instanceURL, accessToken string, expiresAt time.Time) (token, newExpiry string, err error)
RotateSelf replaces the calling personal access token (needs the self_rotate scope). The old token stops working at once; the new secret is returned once, with its expiry date.
func (*Client) SetEnvironmentURL ¶
func (c *Client) SetEnvironmentURL(ctx context.Context, instanceURL, accessToken, projectPath string, envID int64, externalURL string) error
SetEnvironmentURL points an environment at the page it serves.
func (*Client) StopEnvironment ¶
func (c *Client) StopEnvironment(ctx context.Context, instanceURL, accessToken, projectPath, name string) error
StopEnvironment stops the environment called name. A missing environment is not an error: there is nothing left to stop.
func (*Client) UpdateDeploymentStatus ¶
func (c *Client) UpdateDeploymentStatus(ctx context.Context, instanceURL, accessToken, projectPath string, id int64, status DeploymentStatus) error
UpdateDeploymentStatus moves a deployment to status. Sending the same status twice is harmless.
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 DeploymentStatus ¶
type DeploymentStatus string
DeploymentStatus is GitLab's own "status" enum for a deployment.
const ( DeploymentRunning DeploymentStatus = "running" DeploymentSuccess DeploymentStatus = "success" DeploymentFailed DeploymentStatus = "failed" DeploymentCanceled DeploymentStatus = "canceled" )
Deployment statuses Levelrail reports.
type Environment ¶
Environment is a GitLab environment as the Environments API returns it.
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.