Documentation
¶
Overview ¶
Package giteaapp implements OAuth2 and the small slice of Gitea's REST API this control plane needs once connected.
Methods take instanceURL explicitly rather than baking one into the Client, the same reasoning internal/gitlabapp's own doc comment gives: Gitea is almost always self-hosted, never a fixed host like api.github.com. Repos are addressed by an "owner/repo" pair, not a numeric ID: Gitea's REST API is GitHub-shaped here, unlike GitLab's own numeric project ID.
Index ¶
- Constants
- Variables
- func AuthorizeURL(instanceURL, clientID, redirectURI, state, codeChallenge string) string
- func VerifySignature(secret string, body []byte, header string) bool
- type Access
- type Account
- type Branch
- type Client
- func (c *Client) CompareChangedFiles(ctx context.Context, instanceURL, accessToken, fullName, base, head string) ([]string, error)
- func (c *Client) CreateCommitStatus(ctx context.Context, instanceURL, accessToken, fullName, sha string, ...) error
- func (c *Client) CreateIssueComment(ctx context.Context, instanceURL, accessToken, fullName string, number int, ...) (int64, error)
- func (c *Client) CreateOAuthApp(ctx context.Context, instanceURL, accessToken, name, redirectURI string) (OAuthApp, error)
- func (c *Client) CreateRepoWebhook(ctx context.Context, ...) error
- func (c *Client) CurrentUser(ctx context.Context, instanceURL, accessToken string) (Account, error)
- func (c *Client) DeleteOAuthApp(ctx context.Context, instanceURL, accessToken string, appID int64) error
- func (c *Client) DeleteRepoWebhook(ctx context.Context, instanceURL, accessToken, fullName string, hookID int64) error
- func (c *Client) EnsureRepoWebhook(ctx context.Context, ...) (Webhook, error)
- func (c *Client) ExchangeCode(ctx context.Context, ...) (Tokens, error)
- func (c *Client) GetRepo(ctx context.Context, instanceURL, accessToken, fullName string) (Repo, error)
- func (c *Client) ListBranches(ctx context.Context, instanceURL, accessToken, fullName string) ([]Branch, error)
- func (c *Client) ListIssueComments(ctx context.Context, instanceURL, accessToken, fullName string, number int) ([]gitprovider.Comment, error)
- func (c *Client) ListOrgs(ctx context.Context, instanceURL, accessToken string) ([]string, error)
- func (c *Client) ListOwnerRepos(ctx context.Context, instanceURL, accessToken, owner string, ...) ([]Repo, gitprovider.ListResult, error)
- func (c *Client) ListRepoWebhooks(ctx context.Context, instanceURL, accessToken, fullName string) ([]Webhook, error)
- func (c *Client) ListRepos(ctx context.Context, instanceURL, accessToken string, ...) ([]Repo, gitprovider.ListResult, error)
- func (c *Client) ProbeAccess(ctx context.Context, instanceURL, accessToken string, ...) (Access, error)
- func (c *Client) PullRequestChangedFiles(ctx context.Context, instanceURL, accessToken, fullName string, number int) ([]string, error)
- func (c *Client) RefreshToken(ctx context.Context, instanceURL, clientID, clientSecret, refreshToken string) (Tokens, error)
- func (c *Client) TestRepoWebhook(ctx context.Context, instanceURL, accessToken, fullName string, hookID int64) error
- func (c *Client) UpdateIssueComment(ctx context.Context, instanceURL, accessToken, fullName string, ...) error
- type CommitStatusState
- type OAuthApp
- type Repo
- type Tokens
- type Webhook
Constants ¶
const DefaultScope = "read:repository write:repository read:user"
DefaultScope requests read and write repository access (needed to list repos/branches and to register a push webhook) plus basic user identification, Gitea's own OAuth2 scope names (docs.gitea.com/development/oauth2-provider).
Variables ¶
var ErrChangedFilesTruncated = errors.New("giteaapp: changed file list is truncated")
ErrChangedFilesTruncated means a change touched more files than the client pages through, so the list is incomplete and must not drive a decision.
Functions ¶
func AuthorizeURL ¶
AuthorizeURL builds Gitea's OAuth2 authorization-code flow's entry point: a real browser redirect (GET), the same "the operator's browser must navigate here itself" shape internal/gitlabapp.AuthorizeURL's own doc comment describes.
Types ¶
type Access ¶
type Access struct {
Login string
Owners []string
Orgs []string
Sampled int
Truncated bool
CanPull bool
CanPush bool
CanAdmin bool
}
Access is what a token can really do, read from the server's own per-repository permissions because Gitea reports no token scopes.
type Client ¶
Client is a small, purpose-built Gitea REST/OAuth client, not a general-purpose Gitea 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 ¶
func (c *Client) CompareChangedFiles(ctx context.Context, instanceURL, accessToken, fullName, base, head string) ([]string, error)
CompareChangedFiles lists the files touched by the commits between base and head.
func (*Client) CreateCommitStatus ¶
func (c *Client) CreateCommitStatus(ctx context.Context, instanceURL, accessToken, fullName, sha string, state CommitStatusState, targetURL, description, statusContext string) error
CreateCommitStatus sets a commit status on sha of fullName ("owner/repo"), authenticated the same way CreateIssueComment is.
func (*Client) CreateIssueComment ¶
func (c *Client) CreateIssueComment(ctx context.Context, instanceURL, accessToken, fullName string, number int, body string) (int64, error)
CreateIssueComment posts a new comment on issue or pull request number of fullName ("owner/repo") and returns its ID.
func (*Client) CreateOAuthApp ¶
func (c *Client) CreateOAuthApp(ctx context.Context, instanceURL, accessToken, name, redirectURI string) (OAuthApp, error)
CreateOAuthApp registers an OAuth2 application under the token's user (POST /user/applications/oauth2, same on Gitea and Forgejo), so connecting needs one bootstrap token instead of hand-copied client credentials. The caller must not store the bootstrap token.
func (*Client) CreateRepoWebhook ¶
func (c *Client) CreateRepoWebhook(ctx context.Context, instanceURL, accessToken, fullName, hookURL, secret string) error
CreateRepoWebhook (idempotent through EnsureRepoWebhook) registers a push and pull_request webhook on fullName ("owner/repo") pointed at hookURL, with secret set as the value Gitea signs each delivery's X-Gitea-Signature header with (HMAC-SHA256, hex digest, no prefix). Gitea also sends X-Hub-Signature-256 in GitHub's own "sha256=<hex>" format for compatibility (docs.gitea.com/usage/webhooks), which is the header verifyGitPushWebhookAuth (internal/api/git_webhook.go) actually checks, so this package needs no signature-parsing code of its own. pull_request must be requested explicitly: without it Gitea never delivers the event internal/webhook's Gitea pull-request parsing expects, so preview environments would silently never trigger for a connected repo, the same reasoning GitLab's and Bitbucket's own CreateProjectWebhook/CreateRepoWebhook already give for their own merge/pull-request event keys.
func (*Client) CurrentUser ¶
CurrentUser returns the user an access token belongs to.
func (*Client) DeleteOAuthApp ¶
func (c *Client) DeleteOAuthApp(ctx context.Context, instanceURL, accessToken string, appID int64) error
DeleteOAuthApp removes an application created by CreateOAuthApp, which is also how a disconnect revokes every token it issued.
func (*Client) DeleteRepoWebhook ¶
func (c *Client) DeleteRepoWebhook(ctx context.Context, instanceURL, accessToken, fullName string, hookID int64) error
DeleteRepoWebhook removes one hook by id.
func (*Client) EnsureRepoWebhook ¶
func (c *Client) EnsureRepoWebhook(ctx context.Context, instanceURL, accessToken, fullName, hookURL, secret string) (Webhook, error)
EnsureRepoWebhook registers the hook once: when a hook already points at hookURL it is updated in place (new secret, events, active) instead of stacking a duplicate that would deliver every push twice.
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, Gitea's documented POST {instance}/login/oauth/access_token (docs.gitea.com/development/oauth2-provider).
func (*Client) GetRepo ¶
func (c *Client) GetRepo(ctx context.Context, instanceURL, accessToken, fullName string) (Repo, error)
GetRepo looks up a single repository by its "owner/repo" full name.
func (*Client) ListBranches ¶
func (c *Client) ListBranches(ctx context.Context, instanceURL, accessToken, fullName string) ([]Branch, error)
ListBranches lists every branch of fullName ("owner/repo"), across as many pages as Gitea returns full pages for, the same pagination shape ListRepos uses.
func (*Client) ListIssueComments ¶
func (c *Client) ListIssueComments(ctx context.Context, instanceURL, accessToken, fullName string, number int) ([]gitprovider.Comment, error)
ListIssueComments returns the comments of issue or pull request number, up to gitprovider.MaxCommentPages pages.
func (*Client) ListOwnerRepos ¶
func (c *Client) ListOwnerRepos(ctx context.Context, instanceURL, accessToken, owner string, opts gitprovider.ListOptions) ([]Repo, gitprovider.ListResult, error)
ListOwnerRepos lists the repositories of one owner, an organization or a user, so an import can be scoped to a single owner instead of everything the token can see. Organizations are tried first, users on a 404.
func (*Client) ListRepoWebhooks ¶
func (c *Client) ListRepoWebhooks(ctx context.Context, instanceURL, accessToken, fullName string) ([]Webhook, error)
ListRepoWebhooks lists the hooks of fullName ("owner/repo").
func (*Client) ListRepos ¶
func (c *Client) ListRepos(ctx context.Context, instanceURL, accessToken string, opts gitprovider.ListOptions) ([]Repo, gitprovider.ListResult, error)
ListRepos lists repositories the token's account owns or collaborates on, page by page until Gitea runs out or the MaxItems cap is reached.
func (*Client) ProbeAccess ¶
func (c *Client) ProbeAccess(ctx context.Context, instanceURL, accessToken string, opts gitprovider.ListOptions) (Access, error)
ProbeAccess samples the repositories the token can reach and folds their permission flags into one summary, so the capability matrix reflects the forge instead of the connection type.
func (*Client) PullRequestChangedFiles ¶
func (c *Client) PullRequestChangedFiles(ctx context.Context, instanceURL, accessToken, fullName string, number int) ([]string, error)
PullRequestChangedFiles lists the files changed by pull request number.
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, Gitea's grant_type "refresh_token" on the same endpoint ExchangeCode uses.
type CommitStatusState ¶
type CommitStatusState string
CommitStatusState is Gitea's own documented "state" enum for POST .../statuses/{sha}.
const ( // CommitStatusPending marks a commit status as still in progress. CommitStatusPending CommitStatusState = "pending" // CommitStatusSuccess marks a commit status as succeeded. CommitStatusSuccess CommitStatusState = "success" // CommitStatusFailure marks a commit status as failed. CommitStatusFailure CommitStatusState = "failure" )
const CommitStatusError CommitStatusState = "error"
CommitStatusError marks a commit status as errored.
type OAuthApp ¶
OAuthApp is an OAuth2 application created on the forge for this control plane. Secret is only returned once, at creation.
type Repo ¶
type Repo struct {
FullName string
Name string
Private bool
DefaultBranch string
CloneURL string
WebURL string
Archived bool
Fork bool
// Admin and Push are the token holder's rights on this repository as
// the server reports them, the only honest source of capability data.
Admin bool
Push bool
Owner string
}
Repo is one Gitea repository accessible to the connected account, the subset of Gitea's Repository object this control plane's repo picker and "use as source" action need.