Help us shape the future of Go! Take the 2026 Go Developer Survey

notifier

package
v0.17.0 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: 21 Imported by: 0

Documentation

Overview

Package notifier provides integrations for posting deployment status notifications to code review platforms such as GitHub and GitLab.

Index

Constants

View Source
const (
	// AgentTaskCommentMarker is the hidden HTML marker used to identify AgentTask PR/MR comments.
	AgentTaskCommentMarker = "<!-- diverge-agent-task -->"
)

Variables

View Source
var (
	// ErrNotGitLabSource indicates the project is not a GitLab project
	ErrNotGitLabSource = errors.New("preview group source is not gitlab")
	// ErrMissingMergeRequest indicates no merge request is associated
	ErrMissingMergeRequest = errors.New("preview group has no merge request number")
)
View Source
var (
	Providers       = registry.New[Notifier]("notifier")
	StatusProviders = registry.New[StatusReporter]("status-reporter")
	GroupProviders  = registry.New[PreviewGroupNotifier]("previewgroup-notifier")
)
View Source
var TaskProviders = registry.New[TaskPhaseNotifier]("task_notifier")

TaskProviders is the registry of TaskPhaseNotifier providers.

Functions

func FormatAgentTaskComment added in v0.16.0

func FormatAgentTaskComment(task *v1alpha1.AgentTask, phaseBadge, reason string) string

FormatAgentTaskComment formats a Markdown PR/MR comment representing an AgentTask's status, preview magic link, LLM token/cost usage, and interactive slash commands.

func ValidateGitHubWebhookSignature

func ValidateGitHubWebhookSignature(payload []byte, signature, secret string) bool

ValidateGitHubWebhookSignature validates a GitHub webhook payload signature using the provided secret. The signature should be the value of the X-Hub-Signature-256 header (e.g. "sha256=...").

Types

type ConditionData

type ConditionData struct {
	Icon    string
	Type    string
	Message string
}

ConditionData represents a single status condition for template rendering.

type GitHubNotifier

type GitHubNotifier struct {
	BaseURL    string
	Token      string
	HTTPClient *http.Client
}

GitHubNotifier implements Notifier by posting and updating issue comments on GitHub pull requests via the REST API.

func NewGitHubNotifier

func NewGitHubNotifier(baseURL, token string) *GitHubNotifier

NewGitHubNotifier creates a Notifier that posts and updates deployment status comments on GitHub pull requests via the GitHub REST API. If baseURL is empty, it defaults to https://api.github.com.

func (*GitHubNotifier) FindExistingComment added in v0.16.0

func (g *GitHubNotifier) FindExistingComment(ctx context.Context, project string, mrID int, marker string) (int64, error)

FindExistingComment searches GitHub issue comments on a PR for a comment containing marker.

func (*GitHubNotifier) PostComment added in v0.16.0

func (g *GitHubNotifier) PostComment(ctx context.Context, project string, mrID int, body string) (int64, error)

PostComment creates a new issue comment on a GitHub PR and returns its comment ID.

func (*GitHubNotifier) PostEnvironmentCreated

func (g *GitHubNotifier) PostEnvironmentCreated(ctx context.Context, env *v1alpha1.Environment) error

PostEnvironmentCreated posts a comment indicating a new environment is being provisioned.

func (*GitHubNotifier) PostEnvironmentFailed

func (g *GitHubNotifier) PostEnvironmentFailed(ctx context.Context, env *v1alpha1.Environment, reason string) error

PostEnvironmentFailed posts a comment indicating the environment deployment failed.

func (*GitHubNotifier) PostEnvironmentReady

func (g *GitHubNotifier) PostEnvironmentReady(ctx context.Context, env *v1alpha1.Environment) error

PostEnvironmentReady posts a comment indicating the environment is ready with its preview URL.

func (*GitHubNotifier) PostEnvironmentTeardown

func (g *GitHubNotifier) PostEnvironmentTeardown(ctx context.Context, env *v1alpha1.Environment) error

PostEnvironmentTeardown posts a comment indicating the environment is being torn down.

func (*GitHubNotifier) UpdateComment added in v0.16.0

func (g *GitHubNotifier) UpdateComment(ctx context.Context, project string, _ int, commentID int64, body string) error

UpdateComment updates an existing issue comment on a GitHub PR.

func (*GitHubNotifier) UpdateEnvironmentStatus

func (g *GitHubNotifier) UpdateEnvironmentStatus(ctx context.Context, env *v1alpha1.Environment) error

UpdateEnvironmentStatus is a no-op for GitHub; status is conveyed via comments.

type GitHubPreviewGroupNotifier

type GitHubPreviewGroupNotifier struct {
	BaseURL    string
	Token      string
	HTTPClient *http.Client
}

GitHubPreviewGroupNotifier implements PreviewGroupNotifier for GitHub.

func NewGitHubPreviewGroupNotifier

func NewGitHubPreviewGroupNotifier(baseURL, token string) *GitHubPreviewGroupNotifier

NewGitHubPreviewGroupNotifier creates a GitHub-backed notifier that posts preview group status to pull request comments using the GitHub API.

func (*GitHubPreviewGroupNotifier) PostGroupCreated

func (g *GitHubPreviewGroupNotifier) PostGroupCreated(ctx context.Context, pg *v1alpha1.PreviewGroup) error

PostGroupCreated performs its designated operation.

func (*GitHubPreviewGroupNotifier) PostGroupFailed

func (g *GitHubPreviewGroupNotifier) PostGroupFailed(ctx context.Context, pg *v1alpha1.PreviewGroup, reason string) error

PostGroupFailed performs its designated operation.

func (*GitHubPreviewGroupNotifier) PostGroupReady

PostGroupReady performs its designated operation.

func (*GitHubPreviewGroupNotifier) PostGroupTeardown

func (g *GitHubPreviewGroupNotifier) PostGroupTeardown(ctx context.Context, pg *v1alpha1.PreviewGroup) error

PostGroupTeardown performs its designated operation.

func (*GitHubPreviewGroupNotifier) UpdateGroupStatus

func (g *GitHubPreviewGroupNotifier) UpdateGroupStatus(ctx context.Context, pg *v1alpha1.PreviewGroup) error

UpdateGroupStatus performs its designated operation.

type GitHubStatusReporter

type GitHubStatusReporter struct {
	BaseURL    string
	Token      string
	HTTPClient *http.Client
}

GitHubStatusReporter reports commit statuses to GitHub.

func NewGitHubStatusReporter

func NewGitHubStatusReporter(baseURL, token string) *GitHubStatusReporter

NewGitHubStatusReporter creates a reporter that updates GitHub commit statuses via the Statuses API.

func (*GitHubStatusReporter) PostCommitStatus

func (g *GitHubStatusReporter) PostCommitStatus(ctx context.Context, env *v1alpha1.Environment, state, description string) error

PostCommitStatus performs its designated operation.

type GitLabNotifier

type GitLabNotifier struct {
	BaseURL    string
	Token      string
	HTTPClient *http.Client
}

GitLabNotifier implements Notifier by posting and updating merge request notes via the GitLab REST API v4.

func NewGitLabNotifier

func NewGitLabNotifier(baseURL, token string) *GitLabNotifier

NewGitLabNotifier creates a Notifier that posts and updates deployment status notes on GitLab merge requests via the GitLab REST API v4.

func (*GitLabNotifier) FindExistingComment added in v0.16.0

func (g *GitLabNotifier) FindExistingComment(ctx context.Context, project string, mrID int, marker string) (int64, error)

FindExistingComment searches GitLab merge request notes for a note containing marker.

func (*GitLabNotifier) PostComment added in v0.16.0

func (g *GitLabNotifier) PostComment(ctx context.Context, project string, mrID int, body string) (int64, error)

PostComment creates a new merge request note on GitLab and returns its note ID.

func (*GitLabNotifier) PostEnvironmentCreated

func (g *GitLabNotifier) PostEnvironmentCreated(ctx context.Context, env *v1alpha1.Environment) error

PostEnvironmentCreated posts a note indicating a new environment is being provisioned.

func (*GitLabNotifier) PostEnvironmentFailed

func (g *GitLabNotifier) PostEnvironmentFailed(ctx context.Context, env *v1alpha1.Environment, reason string) error

PostEnvironmentFailed posts a note indicating the environment deployment failed.

func (*GitLabNotifier) PostEnvironmentReady

func (g *GitLabNotifier) PostEnvironmentReady(ctx context.Context, env *v1alpha1.Environment) error

PostEnvironmentReady posts a note indicating the environment is ready with its preview URL.

func (*GitLabNotifier) PostEnvironmentTeardown

func (g *GitLabNotifier) PostEnvironmentTeardown(ctx context.Context, env *v1alpha1.Environment) error

PostEnvironmentTeardown posts a note indicating the environment is being torn down.

func (*GitLabNotifier) UpdateComment added in v0.16.0

func (g *GitLabNotifier) UpdateComment(ctx context.Context, project string, mrID int, commentID int64, body string) error

UpdateComment updates an existing merge request note on GitLab.

func (*GitLabNotifier) UpdateEnvironmentStatus

func (g *GitLabNotifier) UpdateEnvironmentStatus(ctx context.Context, env *v1alpha1.Environment) error

UpdateEnvironmentStatus re-renders and updates the existing note with current status.

type GitLabPreviewGroupNotifier

type GitLabPreviewGroupNotifier struct {
	BaseURL    string
	Token      string
	HTTPClient *http.Client
}

GitLabPreviewGroupNotifier implements PreviewGroupNotifier for GitLab.

func NewGitLabPreviewGroupNotifier

func NewGitLabPreviewGroupNotifier(baseURL, token string) *GitLabPreviewGroupNotifier

NewGitLabPreviewGroupNotifier performs its designated operation.

func (*GitLabPreviewGroupNotifier) PostGroupCreated

func (g *GitLabPreviewGroupNotifier) PostGroupCreated(ctx context.Context, pg *v1alpha1.PreviewGroup) error

PostGroupCreated performs its designated operation.

func (*GitLabPreviewGroupNotifier) PostGroupFailed

func (g *GitLabPreviewGroupNotifier) PostGroupFailed(ctx context.Context, pg *v1alpha1.PreviewGroup, reason string) error

PostGroupFailed performs its designated operation.

func (*GitLabPreviewGroupNotifier) PostGroupReady

PostGroupReady performs its designated operation.

func (*GitLabPreviewGroupNotifier) PostGroupTeardown

func (g *GitLabPreviewGroupNotifier) PostGroupTeardown(ctx context.Context, pg *v1alpha1.PreviewGroup) error

PostGroupTeardown performs its designated operation.

func (*GitLabPreviewGroupNotifier) UpdateGroupStatus

func (g *GitLabPreviewGroupNotifier) UpdateGroupStatus(ctx context.Context, pg *v1alpha1.PreviewGroup) error

UpdateGroupStatus performs its designated operation.

type GitLabStatusReporter

type GitLabStatusReporter struct {
	BaseURL    string
	Token      string
	HTTPClient *http.Client
}

GitLabStatusReporter reports commit statuses to GitLab.

func NewGitLabStatusReporter

func NewGitLabStatusReporter(baseURL, token string) *GitLabStatusReporter

NewGitLabStatusReporter creates a reporter that updates GitLab commit statuses via the Commits API.

func (*GitLabStatusReporter) PostCommitStatus

func (g *GitLabStatusReporter) PostCommitStatus(ctx context.Context, env *v1alpha1.Environment, state, description string) error

PostCommitStatus performs its designated operation.

type NoopNotifier

type NoopNotifier struct{}

NoopNotifier is a Notifier that silently discards all notifications. It is used when no external notification platform is configured.

func (*NoopNotifier) PostEnvironmentCreated

func (n *NoopNotifier) PostEnvironmentCreated(ctx context.Context, env *v1alpha1.Environment) error

PostEnvironmentCreated intentionally performs no notification; all lifecycle methods return nil.

func (*NoopNotifier) PostEnvironmentFailed

func (n *NoopNotifier) PostEnvironmentFailed(ctx context.Context, env *v1alpha1.Environment, reason string) error

PostEnvironmentFailed intentionally performs no notification; all lifecycle methods return nil.

func (*NoopNotifier) PostEnvironmentReady

func (n *NoopNotifier) PostEnvironmentReady(ctx context.Context, env *v1alpha1.Environment) error

PostEnvironmentReady intentionally performs no notification; all lifecycle methods return nil.

func (*NoopNotifier) PostEnvironmentTeardown

func (n *NoopNotifier) PostEnvironmentTeardown(ctx context.Context, env *v1alpha1.Environment) error

PostEnvironmentTeardown intentionally performs no notification; all lifecycle methods return nil.

func (*NoopNotifier) UpdateEnvironmentStatus

func (n *NoopNotifier) UpdateEnvironmentStatus(ctx context.Context, env *v1alpha1.Environment) error

UpdateEnvironmentStatus intentionally performs no notification; all lifecycle methods return nil.

type NoopPreviewGroupNotifier

type NoopPreviewGroupNotifier struct{}

NoopPreviewGroupNotifier is a dummy implementation.

func (*NoopPreviewGroupNotifier) PostGroupCreated

func (n *NoopPreviewGroupNotifier) PostGroupCreated(ctx context.Context, pg *v1alpha1.PreviewGroup) error

PostGroupCreated performs its designated operation.

func (*NoopPreviewGroupNotifier) PostGroupFailed

func (n *NoopPreviewGroupNotifier) PostGroupFailed(ctx context.Context, pg *v1alpha1.PreviewGroup, reason string) error

PostGroupFailed performs its designated operation.

func (*NoopPreviewGroupNotifier) PostGroupReady

func (n *NoopPreviewGroupNotifier) PostGroupReady(ctx context.Context, pg *v1alpha1.PreviewGroup) error

PostGroupReady performs its designated operation.

func (*NoopPreviewGroupNotifier) PostGroupTeardown

func (n *NoopPreviewGroupNotifier) PostGroupTeardown(ctx context.Context, pg *v1alpha1.PreviewGroup) error

PostGroupTeardown performs its designated operation.

func (*NoopPreviewGroupNotifier) UpdateGroupStatus

func (n *NoopPreviewGroupNotifier) UpdateGroupStatus(ctx context.Context, pg *v1alpha1.PreviewGroup) error

UpdateGroupStatus performs its designated operation.

type NoopStatusReporter

type NoopStatusReporter struct{}

NoopStatusReporter suppresses commit status reporting; PostCommitStatus returns nil.

func (*NoopStatusReporter) PostCommitStatus

func (n *NoopStatusReporter) PostCommitStatus(ctx context.Context, env *v1alpha1.Environment, state, description string) error

PostCommitStatus intentionally performs no notification; returns nil.

type NoopTaskPhaseNotifier added in v0.16.0

type NoopTaskPhaseNotifier struct{}

NoopTaskPhaseNotifier is a default no-op implementation of TaskPhaseNotifier.

func (*NoopTaskPhaseNotifier) NotifyPhaseChange added in v0.16.0

NotifyPhaseChange does nothing.

type Notifier

type Notifier interface {
	PostEnvironmentCreated(ctx context.Context, env *v1alpha1.Environment) error
	PostEnvironmentReady(ctx context.Context, env *v1alpha1.Environment) error
	PostEnvironmentFailed(ctx context.Context, env *v1alpha1.Environment, reason string) error
	PostEnvironmentTeardown(ctx context.Context, env *v1alpha1.Environment) error
	UpdateEnvironmentStatus(ctx context.Context, env *v1alpha1.Environment) error
}

Notifier posts deployment lifecycle events to an external code review platform. Implementations exist for GitHub, GitLab, and a no-op stub.

type PreviewGroupNotifier

type PreviewGroupNotifier interface {
	PostGroupCreated(ctx context.Context, pg *v1alpha1.PreviewGroup) error
	PostGroupReady(ctx context.Context, pg *v1alpha1.PreviewGroup) error
	PostGroupFailed(ctx context.Context, pg *v1alpha1.PreviewGroup, reason string) error
	PostGroupTeardown(ctx context.Context, pg *v1alpha1.PreviewGroup) error
	UpdateGroupStatus(ctx context.Context, pg *v1alpha1.PreviewGroup) error
}

PreviewGroupNotifier posts deployment lifecycle events for PreviewGroups to an external code review platform.

type PreviewGroupServiceTemplateData

type PreviewGroupServiceTemplateData struct {
	Name            string
	Mode            string
	ModeEmoji       string
	ImageOrBaseline string
	Emoji           string
	Phase           string
	Namespace       string
	Reason          string
}

PreviewGroupServiceTemplateData represents the configuration or state for this type.

type PreviewGroupTemplateData

type PreviewGroupTemplateData struct {
	Name         string
	Branch       string
	MR           int
	TTL          string
	URL          string
	BaseURL      string
	HeaderKey    string
	HeaderValue  string
	ServiceCount int
	RunningCount int
	ExpiryTime   string
	Reason       string
	Services     []PreviewGroupServiceTemplateData
}

PreviewGroupTemplateData holds the template payload for rendering preview group Markdown comments.

type SCMCommentClient added in v0.16.0

type SCMCommentClient interface {
	FindExistingComment(ctx context.Context, project string, mrID int, marker string) (int64, error)
	PostComment(ctx context.Context, project string, mrID int, body string) (int64, error)
	UpdateComment(ctx context.Context, project string, mrID int, commentID int64, body string) error
}

SCMCommentClient abstracts PR/MR comment lookup, creation, and updates across GitHub and GitLab.

type SCMTaskNotifier added in v0.16.0

type SCMTaskNotifier struct {
	Underlying SCMCommentClient
	Client     client.Client
}

SCMTaskNotifier posts and updates autonomous AgentTask progress comments on GitHub PRs and GitLab MRs.

func NewGitHubTaskNotifier added in v0.16.0

func NewGitHubTaskNotifier(token, baseURL string, k8sClient client.Client) *SCMTaskNotifier

NewGitHubTaskNotifier creates an SCMTaskNotifier configured for GitHub PR comments.

func NewGitLabTaskNotifier added in v0.16.0

func NewGitLabTaskNotifier(token, baseURL string, k8sClient client.Client) *SCMTaskNotifier

NewGitLabTaskNotifier creates an SCMTaskNotifier configured for GitLab MR notes.

func NewSCMTaskNotifier added in v0.16.0

func NewSCMTaskNotifier(underlying SCMCommentClient) *SCMTaskNotifier

NewSCMTaskNotifier creates an SCMTaskNotifier backed by the provided SCMCommentClient.

func NewTaskNotifier added in v0.16.0

func NewTaskNotifier(provider, token, baseURL string, k8sClient client.Client) *SCMTaskNotifier

NewTaskNotifier creates a provider-specific SCMTaskNotifier when provider is "github" or "gitlab" and token is non-empty; otherwise returns nil.

func (*SCMTaskNotifier) FormatAgentTaskComment added in v0.16.0

func (n *SCMTaskNotifier) FormatAgentTaskComment(task *v1alpha1.AgentTask, phaseBadge, reason string) string

FormatAgentTaskComment formats the Markdown PR/MR comment for an AgentTask.

func (*SCMTaskNotifier) NotifyPhaseChange added in v0.16.0

func (n *SCMTaskNotifier) NotifyPhaseChange(ctx context.Context, task *v1alpha1.AgentTask, _, newPhase v1alpha1.AgentTaskPhase) error

NotifyPhaseChange implements controller.TaskNotifier to bridge phase transitions to SCM PR/MR comments.

func (*SCMTaskNotifier) NotifyTaskCompleted added in v0.16.0

func (n *SCMTaskNotifier) NotifyTaskCompleted(ctx context.Context, task *v1alpha1.AgentTask) error

NotifyTaskCompleted posts or updates the PR/MR comment when an AgentTask completes.

func (*SCMTaskNotifier) NotifyTaskFailed added in v0.16.0

func (n *SCMTaskNotifier) NotifyTaskFailed(ctx context.Context, task *v1alpha1.AgentTask, reason string) error

NotifyTaskFailed posts or updates the PR/MR comment when an AgentTask fails.

func (*SCMTaskNotifier) NotifyTaskStarted added in v0.16.0

func (n *SCMTaskNotifier) NotifyTaskStarted(ctx context.Context, task *v1alpha1.AgentTask) error

NotifyTaskStarted posts or updates the PR/MR comment when an AgentTask starts running.

type StatusReporter

type StatusReporter interface {
	PostCommitStatus(ctx context.Context, env *v1alpha1.Environment, state, description string) error
}

StatusReporter posts commit status checks to SCM platforms for merge gating.

type TaskPhaseNotifier added in v0.16.0

type TaskPhaseNotifier interface {
	NotifyPhaseChange(ctx context.Context, task *v1alpha1.AgentTask, oldPhase, newPhase v1alpha1.AgentTaskPhase) error
}

TaskPhaseNotifier notifies external observers when an AgentTask changes phases.

type TemplateData

type TemplateData struct {
	Name        string
	Branch      string
	Mode        string
	RoutingMode string
	Services    []string
	TTL         string
	URL         string
	NumServices int
	Duration    string
	BaseURL     string
	ExpiryTime  string
	Reason      string
	HeaderKey   string // routing header key (defaults to x-diverge-env)
	HeaderValue string // optional routing header value (defaults to Name)
	Conditions  []ConditionData
}

TemplateData holds the values passed to notification message templates.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL