github_events

Documentation

Index

• Constants
• func RenderGoTpl(tpl string, data any) (string, error)
• func WithCustomPreview(previewTpl string) templates.MessageMutatorOption
• func WithExtraButtons(btns []ExtraButton) templates.MessageMutatorOption
• type CommonEvent
• type Config
  • func MergeConfigs(configs []*source.Config) (Config, error)
• type EventsAPIMatcher
• type ExtraButton
• type FilePatterns
• type GitHubEvent
  • func (g *GitHubEvent) GetEvent() *github.Event
  • func (g *GitHubEvent) Type() string
• type GitHubPullRequest
  • func (g *GitHubPullRequest) GetEvent() *github.Event
  • func (g *GitHubPullRequest) ParsePayload() (any, error)
  • func (g *GitHubPullRequest) Type() string
• type IncludeExcludeRegex
  • func (r *IncludeExcludeRegex) IsDefined(value string) (bool, error)
  • func (r *IncludeExcludeRegex) IsEmpty() bool
• type JSONPathMatcher
  • func NewJSONPathMatcher(log logrus.FieldLogger) *JSONPathMatcher
  • func (j *JSONPathMatcher) IsEventMatchingCriteria(obj json.RawMessage, jsonPath, expValue string) bool
• type NotificationTemplate
  • func (t NotificationTemplate) ToOptions() []templates.MessageMutatorOption
• type On
• type PullRequest
• type PullRequestMatcher
  • func NewPullRequestMatcher(log logrus.FieldLogger, cli *github.Client) *PullRequestMatcher
  • func (w *PullRequestMatcher) IsEventMatchingCriteria(ctx context.Context, criteria PullRequest, pullRequest *github.PullRequest) bool
• type RepositoryConfig
• type Source
  • func NewSource(version string) *Source
  • func (s *Source) Metadata(_ context.Context) (api.MetadataOutput, error)
  • func (s *Source) Stream(ctx context.Context, input source.StreamInput) (source.StreamOutput, error)
• type Watcher
  • func NewWatcher(refreshDuration time.Duration, repositories []RepositoryConfig, ...) (*Watcher, error)
  • func (w *Watcher) AsyncConsumeEvents(ctx context.Context, stream *source.StreamOutput)
  • func (w *Watcher) List(ctx context.Context, owner string, repo string, ...) ([]*github.PullRequest, *github.Response, error)

Constants

const (
	// PluginName is the name of the GitHub events Botkube plugin.
	PluginName = "github-events"
)

Functions

func RenderGoTpl

func RenderGoTpl(tpl string, data any) (string, error)

func WithCustomPreview

func WithCustomPreview(previewTpl string) templates.MessageMutatorOption

WithCustomPreview generates a custom api.Message preview.

func WithExtraButtons

func WithExtraButtons(btns []ExtraButton) templates.MessageMutatorOption

WithExtraButtons adds extra buttons to the first section of the api.Message.

Types

type CommonEvent

type CommonEvent interface {
	ParsePayload() (payload any, err error)
	Type() string
	GetEvent() *github.Event
}

CommonEvent defines unified event. As a result we can process both events from /events API and custom e.g. list of all active pull requests.

type Config

type Config struct {
	Log config.Logger `yaml:"log"`

	// GitHub configuration.
	GitHub gh.ClientConfig `yaml:"github"`

	// RefreshDuration defines how often we should call GitHub REST API to check repository events.
	// It's the same for all configured repositories. For example, if you configure 5s refresh time, and you have 3 repositories registered,
	// we will execute maximum 2160 calls which easily fits into PAT rate limits.
	// You can create multiple plugins configuration with dedicated tokens to have the rate limits increased.
	//
	// NOTE:
	// - we use conditional requests (https://docs.github.com/en/rest/overview/resources-in-the-rest-api?apiVersion=2022-11-28#conditional-requests), so if there are no events the call doesn't count against your rate limits.
	// - if you configure file pattern matcher for merged pull request events we execute one more additional call to check which files were changed in the context of a given pull request
	//
	// Rate limiting: https://docs.github.com/en/rest/overview/resources-in-the-rest-api?apiVersion=2022-11-28#rate-limiting
	RefreshDuration time.Duration `yaml:"refreshDuration"`

	// List of repository configurations.
	Repositories []RepositoryConfig `yaml:"repositories"`
}

Config represents the main configuration.

func MergeConfigs

func MergeConfigs(configs []*source.Config) (Config, error)

MergeConfigs merges all input configuration.

type EventsAPIMatcher

type EventsAPIMatcher struct {
	// Type defines event type.
	// Required.
	Type string `yaml:"type"`

	// The JSONPath expression to filter events
	JSONPath string `yaml:"jsonPath"`

	// The value to match in the JSONPath result
	Value string `yaml:"value"`

	// NotificationTemplate defines custom notification template.
	NotificationTemplate NotificationTemplate `yaml:"notificationTemplate,omitempty"`
}

EventsAPIMatcher defines matchers for /events API.

type ExtraButton

type ExtraButton struct {
	// DisplayName for the extra button.
	DisplayName string `yaml:"displayName"`

	// CommandTpl template for the extra button.
	CommandTpl string `yaml:"commandTpl"`

	// URL to open. If specified CommandTpl is ignored.
	URL string `yaml:"url"`

	// Style for button.
	Style string `yaml:"style"`
}

ExtraButton represents the extra button configuration in notification templates.

type FilePatterns

type FilePatterns struct {
	// Includes file patterns.
	Include []string `yaml:"include"`

	// Excludes file patterns.
	Exclude []string `yaml:"exclude"`
}

FilePatterns represents the file patterns configuration.

type GitHubEvent

type GitHubEvent struct {
	*github.Event
}

func (*GitHubEvent) GetEvent

func (g *GitHubEvent) GetEvent() *github.Event

func (*GitHubEvent) Type

func (g *GitHubEvent) Type() string

type GitHubPullRequest

type GitHubPullRequest struct {
	RepoName string
	*github.PullRequest
}

func (*GitHubPullRequest) GetEvent

func (g *GitHubPullRequest) GetEvent() *github.Event

func (*GitHubPullRequest) ParsePayload

func (g *GitHubPullRequest) ParsePayload() (any, error)

func (*GitHubPullRequest) Type

func (g *GitHubPullRequest) Type() string

type IncludeExcludeRegex

type IncludeExcludeRegex struct {
	Include []string `yaml:"include"`
	Exclude []string `yaml:"exclude"`
}

IncludeExcludeRegex defines regex filter criteria.

func (*IncludeExcludeRegex) IsDefined

func (r *IncludeExcludeRegex) IsDefined(value string) (bool, error)

IsDefined checks if a given value is defined by a given file pattern matcher. Firstly, it checks if the value is excluded. If not, then it checks if the value is included.

func (*IncludeExcludeRegex) IsEmpty

func (r *IncludeExcludeRegex) IsEmpty() bool

type JSONPathMatcher

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

func NewJSONPathMatcher

func NewJSONPathMatcher(log logrus.FieldLogger) *JSONPathMatcher

func (*JSONPathMatcher) IsEventMatchingCriteria

func (j *JSONPathMatcher) IsEventMatchingCriteria(obj json.RawMessage, jsonPath, expValue string) bool

type NotificationTemplate

type NotificationTemplate struct {
	// Extra buttons in the notification template.
	ExtraButtons []ExtraButton `yaml:"extraButtons"`
	PreviewTpl   string        `yaml:"previewTpl"`
}

NotificationTemplate represents the notification template configuration.

func (NotificationTemplate) ToOptions

func (t NotificationTemplate) ToOptions() []templates.MessageMutatorOption

type On

type On struct {
	PullRequests []PullRequest `yaml:"pullRequests"`
	// EventsAPI watches for /events API
	EventsAPI []EventsAPIMatcher `yaml:"events,omitempty"`
}

On defines allowed GitHub matcher criteria.

type PullRequest

type PullRequest struct {
	// Types patterns defines if we should watch only for pull requests with given state criteria.
	// Allowed values: open, closed, merged.
	Types []string `yaml:"types,omitempty"`
	// Paths patterns defines if we should watch only for pull requests with given files criteria.
	Paths IncludeExcludeRegex `yaml:"paths,omitempty"`
	// Labels patterns define if we should watch only for pull requests with given labels criteria.
	Labels IncludeExcludeRegex `yaml:"labels,omitempty"`
	// NotificationTemplate defines custom notification template.
	NotificationTemplate NotificationTemplate `yaml:"notificationTemplate,omitempty"`
}

type PullRequestMatcher

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

PullRequestMatcher knows how to validate if a given GitHub pull request matches defines criteria.

func NewPullRequestMatcher

func NewPullRequestMatcher(log logrus.FieldLogger, cli *github.Client) *PullRequestMatcher

NewPullRequestMatcher returns a new PullRequestMatcher instance.

func (*PullRequestMatcher) IsEventMatchingCriteria

func (w *PullRequestMatcher) IsEventMatchingCriteria(ctx context.Context, criteria PullRequest, pullRequest *github.PullRequest) bool

IsEventMatchingCriteria returns true if PR matches all defined criteria.

type RepositoryConfig

type RepositoryConfig struct {
	// Repository name represents the GitHub repository.
	// It is in form 'owner/repository'.
	Name string `yaml:"name"`

	// OnMatchers defines allowed GitHub matcher criteria.
	OnMatchers On `yaml:"on"`

	// BeforeDuration is the duration used to decrease the initial time after used for filtering old events.
	// It is particularly useful during testing, allowing you to set it to 48h to retrieve events older than the plugin's start time.
	// If not specified, the plugin's start time is used as the initial value.
	BeforeDuration time.Duration `yaml:"beforeDuration"`
}

RepositoryConfig represents the configuration for repositories.

type Source

type Source struct {
	source.HandleExternalRequestUnimplemented
	// contains filtered or unexported fields
}

Source implements the source.Source interface.

func NewSource

func NewSource(version string) *Source

NewSource returns a new instance of Source.

func (*Source) Metadata

func (s *Source) Metadata(_ context.Context) (api.MetadataOutput, error)

Metadata returns metadata for the GitHub source plugin.

func (*Source) Stream

func (s *Source) Stream(ctx context.Context, input source.StreamInput) (source.StreamOutput, error)

Stream streams GitHub events.

type Watcher

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

Watcher watches for GitHub events.

func NewWatcher

func NewWatcher(refreshDuration time.Duration, repositories []RepositoryConfig, cli *github.Client, log logrus.FieldLogger) (*Watcher, error)

NewWatcher returns a new Watcher instance.

func (*Watcher) AsyncConsumeEvents

func (w *Watcher) AsyncConsumeEvents(ctx context.Context, stream *source.StreamOutput)

func (*Watcher) List

func (w *Watcher) List(ctx context.Context, owner string, repo string, opts *github.PullRequestListOptions, since time.Time) ([]*github.PullRequest, *github.Response, error)

List the pull requests for the specified repository.

GitHub API docs: https://docs.github.com/en/rest/pulls/pulls#list-pull-requests