common

package
v1.0.0-rc1 Latest Latest
Warning

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

 Go to latest Published: Oct 16, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	EnvGitHubAppID            = config.EnvGitHubAppID
	EnvGitHubAppSlug          = config.EnvGitHubAppSlug
	EnvGitHubAppPrivateKey    = config.EnvGitHubAppPrivateKey
	EnvGitHubAppWebhookSecret = config.EnvGitHubAppWebhookSecret
)
View Source 
const AuthMethodApp = "app"
View Source 
const AuthMethodPAT = "pat"
View Source 
const GitHubAppClientSecret = "clientSecret"
View Source 
const GitHubAppPEM = "pem"

* These are the legacy secrets

View Source 
const GitHubAppWebhookSecret = "webhookSecret"
View Source 
const OwnerTypeOrganization = "Organization"
View Source 
const OwnerTypeUser = "User Account"
View Source 
const PropertyAppClientID = "appClientID"
View Source 
const PropertyAppID = "appID"

* When connecting to the owner with a GitHub App, * these are the properties we get back from GitHub, * through the app creation / installation flow.

View Source 
const PropertyAppInstallationID = "appInstallationID"
View Source 
const PropertyAppInstallationURL = "appInstallationURL"
View Source 
const PropertyAppSlug = "appSlug"
View Source 
const PropertyAppState = "appState"
View Source 
const PropertyAppURL = "appURL"
View Source 
const PropertyAuthMethod = "authMethod"

* Two authentication methods are supported: * - Personal Access Token (PAT) * - GitHub App

View Source 
const PropertyOwner = "owner"
View Source 
const PropertyOwnerType = "ownerType"

* An integration can be connected to: * - A user account * - An organization

View Source 
const SecretAppClientSecret = "appClientSecret"
View Source 
const SecretAppPEM = "appPEM"
View Source 
const SecretAppWebhookSecret = "appWebhookSecret"
View Source 
const SecretPAT = "pat"

* Secrets for the integration: * - Personal Access Token (PAT) * - GitHub App private key (App) * - GitHub App client secret (App) * - GitHub App webhook secret (App)

Variables

This section is empty.

Functions

func AppInstallationURL added in v0.20.0 

func AppInstallationURL(properties core.IntegrationPropertyStorageReader, installationID string) (string, error)

func AppURL added in v0.20.0 

func AppURL(properties core.IntegrationPropertyStorageReader, appSlug string) (string, error)

func EnsureRepoInMetadata 

func EnsureRepoInMetadata(ctx core.MetadataWriter, integration core.IntegrationContext, httpCtx core.HTTPContext, configuration any) error

func ExtractAction 

func ExtractAction(data map[string]any) (string, bool)

func FindSecret 

func FindSecret(ctx core.IntegrationContext, secretName string) (string, error)

func HostedAppConfigured 

func HostedAppConfigured() bool

func HostedAppInstallURL 

func HostedAppInstallURL(slug, state string) string

func HostedInstallationSettingsURL 

func HostedInstallationSettingsURL(tx *gorm.DB, integrationID uuid.UUID) (string, error)

func InstallationSettingsURL 

func InstallationSettingsURL(installation models.VCSProviderInstallation) string

InstallationSettingsURL is the GitHub page where an admin manages this App installation. GitHub's html_url wins. Account login and type fill the same page when catalog sync has not stored that URL yet.

func IsExpression added in v0.20.0 

func IsExpression(s string) bool

IsExpression reports whether the given string contains an expression placeholder (e.g. `{{ ... }}`). Useful in Setup paths to skip strict validation of values that will only be known at execution time.

func IsForbiddenError 

func IsForbiddenError(err error) bool

func IsNotFoundError added in v0.20.0 

func IsNotFoundError(err error) bool

func LegacyAppPrivateKey 

func LegacyAppPrivateKey(ctx core.IntegrationContext, metadata Metadata) (string, error)

LegacyAppPrivateKey returns the PEM for a legacy GitHub App connection. Hosted connections use the process key. Customer-created apps use the integration secret.

func ListInstallationBranchNames 

func ListInstallationBranchNames(
	httpCtx core.HTTPContext,
	appID int64,
	privateKey string,
	installationID, repositoryID int64,
	repository string,
) ([]string, error)

ListInstallationBranchNames returns branch names visible to a GitHub App installation. Callers pass the repository ID so the token can read that repository before a binding grant is committed.

func RestrictHostedAppTransport 

func RestrictHostedAppTransport(transport *ghinstallation.Transport, repositoryIDs []int64) error

func SanitizeAssignees 

func SanitizeAssignees(assignees []string) []string

func SignHostedAppInstallState 

func SignHostedAppInstallState(secret string, organizationID uuid.UUID) (string, error)

func StatusCode 

func StatusCode(err error) int

func VerifyHostedAppInstallState 

func VerifyHostedAppInstallState(secret, state string) (uuid.UUID, error)

func VerifySignature 

func VerifySignature(ctx core.WebhookRequestContext) (int, error)

func WhitelistedAction 

func WhitelistedAction(data map[string]any, allowed []string) bool

func WithWebhookLogger 

func WithWebhookLogger(ctx core.WebhookRequestContext, triggerName string) core.WebhookRequestContext

Types

type Client added in v0.20.0 

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

func NewClient 

func NewClient(ctx core.IntegrationContext, httpCtx core.HTTPContext) (*Client, error)

func (*Client) AddIssueAssignees added in v0.20.0 

func (c *Client) AddIssueAssignees(ctx context.Context, repository string, issueNumber int, assignees []string) (*github.Issue, *github.Response, error)

func (*Client) AddLabelsToIssue added in v0.20.0 

func (c *Client) AddLabelsToIssue(ctx context.Context, repository string, issueNumber int, labels []string) ([]*github.Label, *github.Response, error)

func (*Client) AddPullRequestReviewers added in v0.26.0 

func (c *Client) AddPullRequestReviewers(ctx context.Context, repository string, pullNumber int, reviewers github.ReviewersRequest) (*github.PullRequest, *github.Response, error)

func (*Client) CancelWorkflowRun added in v0.20.0 

func (c *Client) CancelWorkflowRun(repository string, workflowRunID int64) (*github.Response, error)

func (*Client) CreateDeployment added in v0.21.0 

func (c *Client) CreateDeployment(ctx context.Context, repository string, request *github.DeploymentRequest) (*github.Deployment, *github.Response, error)

func (*Client) CreateDeploymentStatus added in v0.21.0 

func (c *Client) CreateDeploymentStatus(ctx context.Context, repository string, deploymentID int64, request *github.DeploymentStatusRequest) (*github.DeploymentStatus, *github.Response, error)

func (*Client) CreateHook added in v0.20.0 

func (c *Client) CreateHook(ctx context.Context, repository string, hook *github.Hook) (*github.Hook, *github.Response, error)

func (*Client) CreateIssue added in v0.20.0 

func (c *Client) CreateIssue(ctx context.Context, repository string, issue *github.IssueRequest) (*github.Issue, *github.Response, error)

func (*Client) CreateIssueComment added in v0.20.0 

func (c *Client) CreateIssueComment(ctx context.Context, repository string, issueNumber int, comment *github.IssueComment) (*github.IssueComment, *github.Response, error)

func (*Client) CreateIssueReaction added in v0.20.0 

func (c *Client) CreateIssueReaction(ctx context.Context, repository string, commentID int64, content string) (*github.Reaction, *github.Response, error)

func (*Client) CreatePullRequest added in v0.20.0 

func (c *Client) CreatePullRequest(ctx context.Context, repository string, pullRequest *github.NewPullRequest) (*github.PullRequest, *github.Response, error)

func (*Client) CreatePullRequestReview added in v0.20.0 

func (c *Client) CreatePullRequestReview(ctx context.Context, repository string, pullNumber int, review *github.PullRequestReviewRequest) (*github.PullRequestReview, *github.Response, error)

func (*Client) CreateRelease added in v0.20.0 

func (c *Client) CreateRelease(ctx context.Context, repository string, release *github.RepositoryRelease) (*github.RepositoryRelease, *github.Response, error)

func (*Client) CreateReviewCommentReaction added in v0.20.0 

func (c *Client) CreateReviewCommentReaction(ctx context.Context, repository string, commentID int64, content string) (*github.Reaction, *github.Response, error)

func (*Client) CreateStatus added in v0.20.0 

func (c *Client) CreateStatus(ctx context.Context, repository string, sha string, status github.RepoStatus) (*github.RepoStatus, *github.Response, error)

func (*Client) CreateWorkflowDispatchEvent added in v0.20.0 

func (c *Client) CreateWorkflowDispatchEvent(ctx context.Context, repository string, workflowFile string, request github.CreateWorkflowDispatchEventRequest) (*github.WorkflowDispatchRunDetails, *github.Response, error)

func (*Client) DeleteHook added in v0.20.0 

func (c *Client) DeleteHook(ctx context.Context, repository string, hookID int64) (*github.Response, error)

func (*Client) DeleteRef added in v0.20.0 

func (c *Client) DeleteRef(ctx context.Context, repository string, ref string) (*github.Response, error)

func (*Client) DeleteRelease added in v0.20.0 

func (c *Client) DeleteRelease(ctx context.Context, repository string, id int64) (*github.Response, error)

func (*Client) EditIssue added in v0.20.0 

func (c *Client) EditIssue(ctx context.Context, repository string, issueNumber int, issue *github.IssueRequest) (*github.Issue, *github.Response, error)

func (*Client) EditIssueComment added in v0.26.0 

func (c *Client) EditIssueComment(ctx context.Context, repository string, commentID int64, comment *github.IssueComment) (*github.IssueComment, *github.Response, error)

func (*Client) EditPullRequest added in v0.30.0 

func (c *Client) EditPullRequest(ctx context.Context, repository string, pullNumber int, pullRequest *github.PullRequest) (*github.PullRequest, *github.Response, error)

func (*Client) EditRelease added in v0.20.0 

func (c *Client) EditRelease(ctx context.Context, repository string, id int64, release *github.RepositoryRelease) (*github.RepositoryRelease, *github.Response, error)

func (*Client) FindRepository added in v0.20.0 

func (c *Client) FindRepository(repository string) (*github.Repository, error)

func (*Client) GenerateReleaseNotes added in v0.20.0 

func (c *Client) GenerateReleaseNotes(ctx context.Context, repository string, options *github.GenerateNotesOptions) (*github.RepositoryReleaseNotes, *github.Response, error)

func (*Client) GetBranchProtection 

func (c *Client) GetBranchProtection(ctx context.Context, repository, branch string) (*github.Protection, error)

GetBranchProtection returns required status checks for a branch. A missing or unreadable rule is not an error: GitHub answers 404 when the branch is open, and 403 when the installation cannot read Administration rules.

func (*Client) GetCombinedStatus added in v0.25.0 

func (c *Client) GetCombinedStatus(ctx context.Context, repository string, ref string, opts *github.ListOptions) (*github.CombinedStatus, *github.Response, error)

func (*Client) GetDependabotAlert 

func (c *Client) GetDependabotAlert(ctx context.Context, repository string, number int) (*github.DependabotAlert, *github.Response, error)

func (*Client) GetIssue added in v0.20.0 

func (c *Client) GetIssue(ctx context.Context, repository string, issueNumber int) (*github.Issue, *github.Response, error)

func (*Client) GetLatestRelease added in v0.20.0 

func (c *Client) GetLatestRelease(ctx context.Context, repository string) (*github.RepositoryRelease, *github.Response, error)

func (*Client) GetOrganizationUsageReport added in v0.20.0 

func (c *Client) GetOrganizationUsageReport() (*github.UsageReport, *github.Response, error)

func (*Client) GetPullRequest added in v0.29.0 

func (c *Client) GetPullRequest(ctx context.Context, repository string, pullNumber int) (*github.PullRequest, *github.Response, error)

func (*Client) GetRef added in v0.20.0 

func (c *Client) GetRef(repository string, ref string) (*github.Reference, *github.Response, error)

func (*Client) GetRelease added in v0.20.0 

func (c *Client) GetRelease(ctx context.Context, repository string, id int64) (*github.RepositoryRelease, *github.Response, error)

func (*Client) GetReleaseByTag added in v0.20.0 

func (c *Client) GetReleaseByTag(ctx context.Context, repository string, tag string) (*github.RepositoryRelease, *github.Response, error)

func (*Client) GetRepositoryPermissionLevel added in v0.20.0 

func (c *Client) GetRepositoryPermissionLevel(ctx context.Context, repository string, username string) (*github.RepositoryPermissionLevel, *github.Response, error)

func (*Client) GetWorkflowRun added in v0.20.0 

func (c *Client) GetWorkflowRun(repository string, workflowRunID int64) (*github.WorkflowRun, *github.Response, error)

func (*Client) HTTPDo 

func (c *Client) HTTPDo(req *http.Request) (*http.Response, error)

func (*Client) HeadFilter 

func (c *Client) HeadFilter(repository, branch string) string

HeadFilter builds the "owner:branch" value GitHub's pull request list "head" filter requires, using repository to resolve the owner the same way every other call on this client does. If branch already carries an "owner:" prefix (for example, a cross-repository head), it is returned unchanged.

func (*Client) ListAllOpenDependabotAlerts 

func (c *Client) ListAllOpenDependabotAlerts(ctx context.Context, repository string) ([]*github.DependabotAlert, error)

func (*Client) ListBranches added in v0.20.0 

func (c *Client) ListBranches(ctx context.Context, repository string, opts *github.BranchListOptions) ([]*github.Branch, *github.Response, error)

func (*Client) ListCheckRunsForRef added in v0.25.0 

func (c *Client) ListCheckRunsForRef(ctx context.Context, repository string, ref string, opts *github.ListCheckRunsOptions) (*github.ListCheckRunsResults, *github.Response, error)

func (*Client) ListCommits 

func (c *Client) ListCommits(
	ctx context.Context,
	repository string,
	opts *github.CommitsListOptions,
) ([]*github.RepositoryCommit, *github.Response, error)

ListCommits returns one page of a repository's commits.

The commit message carries the trailers a squashed merge collected, which name the co-authors of the work. A pull request listing does not include them.

func (*Client) ListIssueComments 

func (c *Client) ListIssueComments(ctx context.Context, repository string, issueNumber int) ([]*github.IssueComment, error)

ListIssueComments returns an issue's comments oldest first, paginating through every page. It uses the REST Issues.ListComments endpoint, which returns issue comments only, never pull request review comments.

func (*Client) ListLabelsForIssue added in v0.20.0 

func (c *Client) ListLabelsForIssue(ctx context.Context, repository string, issueNumber int) ([]*github.Label, *github.Response, error)

func (*Client) ListLabelsForRepository 

func (c *Client) ListLabelsForRepository(ctx context.Context, repository string, opts *github.ListOptions) ([]*github.Label, *github.Response, error)

ListLabelsForRepository lists the labels defined in a repository, not the labels of a single issue. Settings screens use it to offer the labels that exist instead of a hardcoded list.

func (*Client) ListNewestOpenIssues 

func (c *Client) ListNewestOpenIssues(ctx context.Context, repository string, limit int) ([]*github.Issue, error)

ListNewestOpenIssues reads the newest open issues of a repository, newest first.

It asks GraphQL instead of the REST issue list because REST answers that list with pull requests in the same page. A caller that wants N issues then has to read a larger page and drop the pull requests, and a repository with many open pull requests returns few issues, or none.

func (*Client) ListOpenDependabotAlerts 

func (c *Client) ListOpenDependabotAlerts(ctx context.Context, repository string, limit int) ([]*github.DependabotAlert, *github.Response, error)

ListOpenDependabotAlerts reads open Dependabot alerts for a repository, newest first. GitHub returns 403 when alerts are turned off or the app cannot read them.

func (*Client) ListPullRequestComments 

func (c *Client) ListPullRequestComments(ctx context.Context, repository string, pullNumber int) ([]*github.PullRequestComment, error)

func (*Client) ListPullRequestReviewComments 

func (c *Client) ListPullRequestReviewComments(
	ctx context.Context,
	repository string,
	pullNumber int,
	reviewID int64,
) ([]*github.PullRequestComment, error)

func (*Client) ListPullRequests 

func (c *Client) ListPullRequests(
	ctx context.Context,
	repository string,
	opts *github.PullRequestListOptions,
) ([]*github.PullRequest, *github.Response, error)

ListPullRequests returns one page of a repository's pull requests.

This is the plain REST endpoint, which draws on the 5000-per-hour budget. Prefer it over a Search query, because Search allows only 30 requests a minute per installation.

func (*Client) ListReleases added in v0.20.0 

func (c *Client) ListReleases(ctx context.Context, repository string, options *github.ListOptions) ([]*github.RepositoryRelease, *github.Response, error)

func (*Client) ListRepositories added in v0.20.0 

func (c *Client) ListRepositories() ([]*github.Repository, error)

func (*Client) ListReviews 

func (c *Client) ListReviews(ctx context.Context, repository string, pullNumber int) ([]*github.PullRequestReview, error)

func (*Client) MarkPullRequestReadyForReview added in v0.29.0 

func (c *Client) MarkPullRequestReadyForReview(ctx context.Context, pullRequestID string) error

MarkPullRequestReadyForReview takes a pull request out of the draft state. GitHub exposes this only through the GraphQL API, so it is the one pull request operation that cannot delegate to the REST client. It takes the pull request node ID (github.PullRequest.NodeID), not the pull request number.

func (*Client) MergePullRequest added in v0.25.0 

func (c *Client) MergePullRequest(ctx context.Context, repository string, pullNumber int, commitMessage string, options *github.PullRequestOptions) (*github.PullRequestMergeResult, *github.Response, error)

func (*Client) RemoveIssueAssignees added in v0.20.0 

func (c *Client) RemoveIssueAssignees(ctx context.Context, repository string, issueNumber int, assignees []string) (*github.Issue, *github.Response, error)

func (*Client) RemoveLabelForIssue added in v0.20.0 

func (c *Client) RemoveLabelForIssue(ctx context.Context, repository string, issueNumber int, label string) (*github.Response, error)

func (*Client) SearchIssues 

func (c *Client) SearchIssues(ctx context.Context, query string, opts *github.SearchOptions) (*github.IssuesSearchResult, *github.Response, error)

SearchIssues wraps the /search/issues endpoint. The Velocity page uses it to list a repository's merged pull requests within a window; keeping the SDK pass-through thin means callers can build any query GitHub Search supports (issues, PRs, drafts, authors) without a new helper per shape.

type GitHubAppMetadata 

type GitHubAppMetadata struct {
	ID       int64  `mapstructure:"id" json:"id"`
	Slug     string `mapstructure:"slug" json:"slug"`
	ClientID string `mapstructure:"clientId" json:"clientId"`
}

type HostedApp 

type HostedApp struct {
	ID            int64
	Slug          string
	PrivateKey    string
	WebhookSecret string
}

HostedApp is SuperPlane Cloud's public GitHub App. The process holds the credentials. Organization integrations reference a global installation.

func HostedAppFromEnv 

func HostedAppFromEnv() (HostedApp, bool)

HostedAppFromEnv returns the public GitHub App from process environment.

func ResolveHostedApp 

func ResolveHostedApp(ctx context.Context) (HostedApp, bool)

ResolveHostedApp returns the public GitHub App for this request. Environment wins. Self-host falls back to the installation row after first-run create.

type HostedAppBinding 

type HostedAppBinding struct {
	App           HostedApp
	Installation  *models.VCSProviderInstallation
	ID            int64
	RepositoryIDs []int64
}

func ResolveHostedAppBinding 

func ResolveHostedAppBinding(ctx core.IntegrationContext) (*HostedAppBinding, error)

type InstallRequest 

type InstallRequest struct {
	ID             string `mapstructure:"id" json:"id,omitempty"`
	AccountLogin   string `mapstructure:"accountLogin" json:"accountLogin,omitempty"`
	RequesterLogin string `mapstructure:"requesterLogin" json:"requesterLogin,omitempty"`
	CreatedAt      string `mapstructure:"createdAt" json:"createdAt,omitempty"`
}

type Metadata 

type Metadata struct {
	InstallationID string            `mapstructure:"installationId" json:"installationId"`
	State          string            `mapstructure:"state" json:"state"`
	Owner          string            `mapstructure:"owner" json:"owner"`
	Repositories   []Repository      `mapstructure:"repositories" json:"repositories"`
	GitHubApp      GitHubAppMetadata `mapstructure:"githubApp" json:"githubApp"`
	// HostedApp is true when this connection installs SuperPlane's public
	// GitHub App. Credentials stay on the process, not on the integration.
	HostedApp bool `mapstructure:"hostedApp" json:"hostedApp"`
	// InstallRequested is true when a non-admin asked a GitHub org admin to
	// install the app. Setup then returned setup_action=request.
	InstallRequested bool `mapstructure:"installRequested" json:"installRequested,omitempty"`
	// InstallRequestedAccount is the GitHub organization (or user) login the
	// member asked an admin to approve.
	InstallRequestedAccount string `mapstructure:"installRequestedAccount" json:"installRequestedAccount,omitempty"`
	// InstallRequests contains every open GitHub App installation request for
	// the member who started this connection. The legacy scalar fields above
	// mirror this collection for compatibility with older clients.
	InstallRequests []InstallRequest `mapstructure:"installRequests" json:"installRequests,omitempty"`
	// SetupReturnPath is the in-app path to open after GitHub setup. Callbacks
	// use it when the browser cookie is missing, for example localhost to ngrok.
	SetupReturnPath string `mapstructure:"setupReturnPath" json:"setupReturnPath,omitempty"`
}

func (Metadata) CurrentInstallRequests 

func (m Metadata) CurrentInstallRequests() []InstallRequest

func (Metadata) HasInstallRequests 

func (m Metadata) HasInstallRequests() bool

func (*Metadata) SetInstallRequests 

func (m *Metadata) SetInstallRequests(requests []InstallRequest)

type NodeMetadata 

type NodeMetadata struct {
	Repository *Repository `json:"repository"`
}

type Repository 

type Repository struct {
	ID   int64  `json:"id"`
	Name string `json:"name"`
	URL  string `json:"url"`
}

type WebhookConfiguration 

type WebhookConfiguration struct {
	EventType  string   `json:"eventType"`
	EventTypes []string `json:"eventTypes"` // Multiple event types (takes precedence over EventType if set)
	Repository string   `json:"repository"`
}

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.