Documentation
¶
Overview ¶
Package githubapp defines the GitHub App reference definition for integrations
Index ¶
- Variables
- func Builder(cfg Config) registry.Builder
- type App
- type Client
- type CodeScanningAlertWebhook
- type Config
- type DependabotAlertWebhook
- type DirectorySync
- type GraphQLClient
- type HealthCheck
- type InstallationCreatedWebhook
- type InstallationDeletedWebhook
- type InstallationMetadata
- type PingWebhook
- type RepositoryAssetPayload
- type RepositorySync
- type SecretScanningAlertWebhook
- type SecurityAdvisory
- type UserInput
- type VulnerabilityAlertPayload
- type VulnerabilityCollect
- type VulnerabilityCollectConfig
Constants ¶
This section is empty.
Variables ¶
var ( // ErrAPIRequest indicates a GitHub API request failed ErrAPIRequest = errors.New("githubapp: api request failed") // ErrAccessTokenMissing indicates the access token is not present in the credential ErrAccessTokenMissing = errors.New("githubapp: access token missing") // ErrCredentialDecode indicates the credential data could not be decoded ErrCredentialDecode = errors.New("githubapp: credential decode failed") // ErrCredentialEncode indicates the credential data could not be encoded ErrCredentialEncode = errors.New("githubapp: credential encode failed") // ErrAppIDMissing indicates the GitHub App ID is missing from operator config ErrAppIDMissing = errors.New("githubapp: app id missing") // ErrInstallationIDMissing indicates the GitHub App installation ID is missing ErrInstallationIDMissing = errors.New("githubapp: installation id missing") // ErrPrivateKeyMissing indicates the GitHub App private key is missing from operator config ErrPrivateKeyMissing = errors.New("githubapp: private key missing") // ErrPrivateKeyInvalid indicates the GitHub App private key could not be parsed ErrPrivateKeyInvalid = errors.New("githubapp: private key invalid") // ErrJWTSigningFailed indicates the GitHub App JWT could not be signed ErrJWTSigningFailed = errors.New("githubapp: jwt signing failed") // ErrInstallationTokenRequestFailed indicates the installation token exchange failed ErrInstallationTokenRequestFailed = errors.New("githubapp: installation token request failed") // ErrInstallationTokenEmpty indicates the installation token response was empty ErrInstallationTokenEmpty = errors.New("githubapp: installation token empty") // ErrWebhookSecretMissing indicates the GitHub App webhook secret is missing from operator config ErrWebhookSecretMissing = errors.New("githubapp: webhook secret missing") // ErrWebhookEventMissing indicates the GitHub webhook event header was not sent ErrWebhookEventMissing = errors.New("githubapp: webhook event missing") // ErrWebhookSignatureMissing indicates the GitHub webhook signature header was not sent ErrWebhookSignatureMissing = errors.New("githubapp: webhook signature missing") // ErrWebhookSignatureMismatch indicates the GitHub webhook signature did not match ErrWebhookSignatureMismatch = errors.New("githubapp: webhook signature mismatch") // ErrAppSlugMissing indicates the GitHub App slug is missing from operator config ErrAppSlugMissing = errors.New("githubapp: app slug missing") // ErrClientType indicates the provided client is not a supported type ErrClientType = errors.New("githubapp: unexpected client type") // ErrOperationConfigInvalid indicates operation config could not be decoded ErrOperationConfigInvalid = errors.New("githubapp: operation config invalid") // ErrResultEncode indicates an operation result could not be serialized ErrResultEncode = errors.New("githubapp: result encode failed") // ErrAuthStartInputInvalid indicates auth start input could not be decoded ErrAuthStartInputInvalid = errors.New("githubapp: auth start input invalid") // ErrAuthCompleteInputInvalid indicates auth completion input could not be decoded ErrAuthCompleteInputInvalid = errors.New("githubapp: auth complete input invalid") // ErrAuthStateEncode indicates auth state could not be serialized ErrAuthStateEncode = errors.New("githubapp: auth state encode failed") // ErrAuthStateDecode indicates auth state could not be decoded ErrAuthStateDecode = errors.New("githubapp: auth state decode failed") // ErrAuthStateMismatch indicates the callback state did not match the saved auth state ErrAuthStateMismatch = errors.New("githubapp: auth state mismatch") // ErrAuthStateGenerate indicates the CSRF state token could not be generated ErrAuthStateGenerate = errors.New("githubapp: auth state generate failed") // ErrInstallationMetadataEncode indicates installation metadata could not be encoded ErrInstallationMetadataEncode = errors.New("githubapp: installation metadata encode failed") // ErrInstallationMetadataDecode indicates installation metadata could not be decoded from credential data ErrInstallationMetadataDecode = errors.New("githubapp: installation metadata decode failed") // ErrIngestPayloadEncode indicates a collected GitHub payload could not be serialized for ingest ErrIngestPayloadEncode = errors.New("githubapp: ingest payload encode failed") // ErrWebhookPayloadInvalid indicates the webhook payload could not be decoded ErrWebhookPayloadInvalid = errors.New("githubapp: webhook payload invalid") // ErrWebhookMetadataEncode indicates webhook metadata could not be encoded ErrWebhookMetadataEncode = errors.New("githubapp: webhook metadata encode failed") // ErrWebhookPersistFailed indicates webhook side effects could not be persisted ErrWebhookPersistFailed = errors.New("githubapp: webhook persist failed") // ErrWebhookIngestFailed indicates webhook ingest failed ErrWebhookIngestFailed = errors.New("githubapp: webhook ingest failed") )
var ( // DefinitionID is the stable identifier for the GitHub App integration definition DefinitionID = types.NewDefinitionRef("def_01K0GHAPP000000000000000001") // InstallationEventsWebhook is the webhook ref for GitHub App installation-scoped deliveries InstallationEventsWebhook = types.NewWebhookRef("installation.events") )
Functions ¶
Types ¶
type App ¶
type App struct {
// Config holds the operator-supplied GitHub App settings
Config Config
}
App executes the GitHub App webhook verification logic
func (App) Event ¶
func (App) Event(request types.WebhookInboundRequest) (types.WebhookReceivedEvent, error)
Event resolves the inbound webhook payload into one registered GitHub webhook event
func (App) Verify ¶
func (a App) Verify(request types.WebhookInboundRequest) error
Verify validates the HMAC-SHA256 signature on an inbound GitHub webhook request. Follows the GitHub webhook verification pattern: the X-Hub-Signature-256 header contains "sha256=<hex-encoded HMAC-SHA256>" computed using the app webhook secret
type Client ¶
type Client struct {
// APIURL overrides the GitHub API host for local tests
APIURL string
}
Client builds installation-scoped GitHub GraphQL clients
type CodeScanningAlertWebhook ¶
type CodeScanningAlertWebhook struct{}
CodeScanningAlertWebhook ingests one code scanning alert from the webhook payload
func (CodeScanningAlertWebhook) Handle ¶
func (CodeScanningAlertWebhook) Handle(ctx context.Context, request types.WebhookHandleRequest) error
Handle ingests one code scanning alert from the webhook payload
type Config ¶
type Config struct {
// AppID is the GitHub App identifier
AppID string `json:"appid" koanf:"appid" sensitive:"true"`
// PrivateKey is the PEM-encoded RSA private key for the GitHub App
PrivateKey string `json:"privatekey" koanf:"privatekey" sensitive:"true"`
// WebhookSecret is the GitHub App webhook secret for signature verification
WebhookSecret string `json:"webhooksecret" koanf:"webhooksecret" sensitive:"true"`
// AppSlug is the GitHub App slug identifier
AppSlug string `json:"appslug" koanf:"appslug"`
// APIURL overrides the GitHub API host for local tests
APIURL string `json:"-" koanf:"-"`
}
Config holds operator-level credentials for the GitHub App definition
type DependabotAlertWebhook ¶
type DependabotAlertWebhook struct{}
DependabotAlertWebhook ingests one Dependabot alert from the webhook payload
func (DependabotAlertWebhook) Handle ¶
func (DependabotAlertWebhook) Handle(ctx context.Context, request types.WebhookHandleRequest) error
Handle ingests one Dependabot alert from the webhook payload
type DirectorySync ¶
type DirectorySync struct{}
DirectorySync collects GitHub organization members for directory account ingest
func (DirectorySync) IngestHandle ¶
func (d DirectorySync) IngestHandle() types.IngestHandler
IngestHandle adapts directory sync to the ingest operation registration boundary
func (DirectorySync) Run ¶
func (DirectorySync) Run(ctx context.Context, client GraphQLClient) ([]types.IngestPayloadSet, error)
Run collects GitHub organization members and emits directory account ingest payloads
type GraphQLClient ¶
type GraphQLClient interface {
// Query executes a GraphQL query against the GitHub API
Query(ctx context.Context, q any, variables map[string]any) error
}
GraphQLClient is the subset of the GitHub GraphQL client used by this definition
type HealthCheck ¶
type HealthCheck struct{}
HealthCheck validates the GitHub App installation token
func (HealthCheck) Handle ¶
func (h HealthCheck) Handle() types.OperationHandler
Handle adapts the health check to the generic operation registration boundary
func (HealthCheck) Run ¶
func (HealthCheck) Run(ctx context.Context, client GraphQLClient) (json.RawMessage, error)
Run executes the health check using the GitHub GraphQL client
type InstallationCreatedWebhook ¶
type InstallationCreatedWebhook struct{}
InstallationCreatedWebhook sends the GitHub App installation notification
func (InstallationCreatedWebhook) Handle ¶
func (InstallationCreatedWebhook) Handle(ctx context.Context, request types.WebhookHandleRequest) error
Handle sends the GitHub App installation-created Slack notification
type InstallationDeletedWebhook ¶
type InstallationDeletedWebhook struct{}
InstallationDeletedWebhook removes a disconnected GitHub App installation after the uninstall webhook arrives
func (InstallationDeletedWebhook) Handle ¶
func (InstallationDeletedWebhook) Handle(ctx context.Context, request types.WebhookHandleRequest) error
Handle removes the Openlane installation after GitHub confirms the app was uninstalled
type InstallationMetadata ¶
type InstallationMetadata struct {
// InstallationID is the GitHub App installation identifier
InstallationID string `json:"installationId,omitempty" jsonschema:"title=installation ID"`
}
InstallationMetadata holds the stable GitHub App installation identity attributes
func (InstallationMetadata) InstallationIdentity ¶
func (m InstallationMetadata) InstallationIdentity() types.IntegrationInstallationIdentity
InstallationIdentity implements types.InstallationIdentifiable
type PingWebhook ¶
type PingWebhook struct{}
PingWebhook marks a GitHub App webhook endpoint as verified
func (PingWebhook) Handle ¶
func (PingWebhook) Handle(ctx context.Context, request types.WebhookHandleRequest) error
Handle marks the GitHub webhook as verified for the installation
type RepositoryAssetPayload ¶
type RepositoryAssetPayload struct {
// NameWithOwner is the full repository name in owner/repo format
NameWithOwner string `json:"nameWithOwner"`
// IsPrivate reports whether the repository is private
IsPrivate bool `json:"isPrivate"`
// UpdatedAt is the timestamp of the most recent push or metadata update
UpdatedAt time.Time `json:"updatedAt"`
// URL is the canonical web URL of the repository
URL string `json:"url"`
}
RepositoryAssetPayload is the normalized repository payload emitted for Asset ingest
type RepositorySync ¶
type RepositorySync struct{}
RepositorySync collects repositories accessible to the installation as assets
func (RepositorySync) IngestHandle ¶
func (r RepositorySync) IngestHandle() types.IngestHandler
IngestHandle adapts repository sync to the ingest operation registration boundary
func (RepositorySync) Run ¶
func (RepositorySync) Run(ctx context.Context, client GraphQLClient) ([]types.IngestPayloadSet, error)
Run enumerates repositories accessible to the installation and emits Asset ingest payloads
type SecretScanningAlertWebhook ¶
type SecretScanningAlertWebhook struct{}
SecretScanningAlertWebhook ingests one secret scanning alert from the webhook payload
func (SecretScanningAlertWebhook) Handle ¶
func (SecretScanningAlertWebhook) Handle(ctx context.Context, request types.WebhookHandleRequest) error
Handle ingests one secret scanning alert from the webhook payload
type SecurityAdvisory ¶
type SecurityAdvisory struct {
// GHSAID is the GitHub Security Advisory identifier
GHSAID string `json:"ghsa_id,omitempty"`
// Summary is the short advisory summary
Summary string `json:"summary,omitempty"`
// Description is the full advisory description
Description string `json:"description,omitempty"`
// Severity is the advisory severity string reported by GitHub
Severity string `json:"severity,omitempty"`
// CVEID is the advisory CVE identifier when present
CVEID string `json:"cve_id,omitempty"`
}
SecurityAdvisory is the normalized advisory shape used by the GitHub App mapping
type UserInput ¶
type UserInput struct {
// FilterExpr limits imported records to envelopes matching the CEL expression
FilterExpr string `` /* 173-byte string literal not displayed */
}
UserInput holds installation-specific configuration collected from the user
type VulnerabilityAlertPayload ¶
type VulnerabilityAlertPayload struct {
// Number is the GitHub alert number
Number int `json:"number,omitempty"`
// State is the current lifecycle state of the alert
State string `json:"state,omitempty"`
// HTMLURL is the GitHub UI URL for the alert
HTMLURL string `json:"html_url,omitempty"`
// CreatedAt is when GitHub created the alert
CreatedAt time.Time `json:"created_at,omitempty"`
// UpdatedAt is when GitHub last updated the alert
UpdatedAt time.Time `json:"updated_at,omitempty"`
// SecurityAdvisory contains the advisory details attached to the alert
SecurityAdvisory SecurityAdvisory `json:"security_advisory"`
}
VulnerabilityAlertPayload is the raw provider payload emitted for ingest
type VulnerabilityCollect ¶
type VulnerabilityCollect struct{}
VulnerabilityCollect collects repository vulnerability alerts for ingest
func (VulnerabilityCollect) IngestHandle ¶
func (v VulnerabilityCollect) IngestHandle() types.IngestHandler
IngestHandle adapts vulnerability collection to the ingest operation registration boundary
func (VulnerabilityCollect) Run ¶
func (VulnerabilityCollect) Run(ctx context.Context, client GraphQLClient, config VulnerabilityCollectConfig) ([]types.IngestPayloadSet, error)
Run collects repository vulnerability alerts and emits ingest payloads
type VulnerabilityCollectConfig ¶
type VulnerabilityCollectConfig struct {
// MaxRepos caps the number of repositories scanned during one run
MaxRepos int `json:"max_repos,omitempty" jsonschema:"description=Optional cap on the number of repositories to scan."`
}
VulnerabilityCollectConfig controls the vulnerability collect operation