Documentation
¶
Index ¶
- func AuthCheckEvent(configDir string, cfg config.ConfigReader, event *normevent.Event) normevent.Event
- func IsAuthorized(event *normevent.Event) bool
- func IsEventAuthorized(event *normevent.Event) bool
- func IsEventAuthorizedWith(event *normevent.Event, opts AuthOptions) bool
- func IsHarnessAuthorized(event *normevent.Event, harnessRole string) bool
- func IsHarnessAuthorizedWith(event *normevent.Event, harnessRole string, opts AuthOptions) bool
- func IsRecognizedBot(actor normevent.Actor) bool
- func KillSwitchActive(configDir string) (bool, error)
- func MergedConfigAgents(configDir string) ([]config.AgentEntry, error)
- func RequiredActorRole(harnessRole string) normevent.ActorRole
- type AuthOptions
- type ExecutionRef
- type Options
- type TriggeredHarness
- func FilterAuthorizedHarnesses(harnesses []TriggeredHarness, event *normevent.Event) []TriggeredHarness
- func FilterAuthorizedHarnessesWith(harnesses []TriggeredHarness, event *normevent.Event, opts AuthOptions) []TriggeredHarness
- func ListTriggeredHarnesses(ctx context.Context, configDir string, cfg config.ConfigReader, ...) ([]TriggeredHarness, error)
- func MatchHarnesses(candidates []TriggeredHarness, event *normevent.Event) ([]TriggeredHarness, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AuthCheckEvent ¶ added in v0.50.0
func AuthCheckEvent(configDir string, cfg config.ConfigReader, event *normevent.Event) normevent.Event
AuthCheckEvent returns a copy of event to pass to the authorization gate (IsEventAuthorized, IsHarnessAuthorized, FilterAuthorizedHarnesses). When the per-repo config enables OWNERS-file authorization, the copy's actor role is upgraded from the OWNERS and OWNERS_ALIASES files in the parent of configDir. The caller's event is not mutated: the upgraded role is used only for the gate, and CEL evaluation keeps seeing the collaborator-API role.
func IsAuthorized ¶
IsAuthorized reports whether event may dispatch a mutation harness (write threshold). It is equivalent to IsHarnessAuthorized with an empty harness role, which fails closed to write.
func IsEventAuthorized ¶ added in v0.50.0
IsEventAuthorized is the event-level dispatch gate, run once per event before harness enumeration. It returns false when the event is denied for every harness: a nil event, a bot whose ADR 0107 lookup did not recognize a registered role, a human whose role lookup failed, or an actor.role below the lowest per-harness threshold (triage). A true result means at least one harness may be authorized; callers must still filter harnesses with IsHarnessAuthorized or FilterAuthorizedHarnesses.
func IsEventAuthorizedWith ¶ added in v0.54.0
func IsEventAuthorizedWith(event *normevent.Event, opts AuthOptions) bool
IsEventAuthorizedWith is IsEventAuthorized under the policy in opts.
func IsHarnessAuthorized ¶ added in v0.50.0
IsHarnessAuthorized reports whether event may dispatch a harness whose role: field is harnessRole. Event-level exceptions (GitHub label-added, recognized bots, GitHub bot review_submitted) authorize every harness; Jira label-added is such an exception only under IsHarnessAuthorizedWith with AuthOptions.JiraLabelsByEditPermission set. Event-level denials deny every harness; the remaining path requires actor.role to satisfy RequiredActorRole(harnessRole).
func IsHarnessAuthorizedWith ¶ added in v0.54.0
func IsHarnessAuthorizedWith(event *normevent.Event, harnessRole string, opts AuthOptions) bool
IsHarnessAuthorizedWith is IsHarnessAuthorized under the policy in opts.
func IsRecognizedBot ¶ added in v0.50.0
IsRecognizedBot reports whether actor is a bot whose bot-role lookup completed and resolved a registered canonical role (ADR 0107).
func KillSwitchActive ¶
KillSwitchActive reads kill_switch from config in configDir.
func MergedConfigAgents ¶
func MergedConfigAgents(configDir string) ([]config.AgentEntry, error)
MergedConfigAgents loads agent entries from per-repo config directory.
func RequiredActorRole ¶ added in v0.50.0
RequiredActorRole returns the minimum actor.role a harness requires, derived from its role: field per the authorization contract's default thresholds. Observation roles (triage, review) require triage; every other role, including an empty, unknown, or custom role, requires write (fail closed).
Types ¶
type AuthOptions ¶ added in v0.54.0
type AuthOptions struct {
// JiraLabelsByEditPermission turns on the Jira label-added exception:
// a Jira label-added event is authorized without a role threshold,
// because Jira requires the Edit Issues permission to change labels.
// Set it only when a jira authorization provider entry is present and
// selects labels: jira_editors (its default); under allowlist or
// project_roles the poller resolves the label author's actor.role from
// that source and the threshold applies.
JiraLabelsByEditPermission bool
}
AuthOptions carries the configuration-derived inputs to the dispatch gate. The zero value is the default policy: a Jira label-added event takes the per-harness role threshold like any other event.
func AuthOptionsFor ¶ added in v0.54.0
func AuthOptionsFor(cfg config.ConfigReader) AuthOptions
AuthOptionsFor derives the dispatch gate policy from the loaded config's jira authorization provider: Jira label-added events get the Edit Issues exception only when a jira provider entry is present and selects labels: jira_editors (the default for an entry). With no jira entry, or under allowlist or project_roles, they take the role threshold.
type ExecutionRef ¶
type ExecutionRef struct {
Agent string `json:"agent"`
Role string `json:"role"`
SourceRepo string `json:"source_repo"`
EventType string `json:"event_type"`
EventPayload string `json:"event_payload"`
TriggerSource string `json:"trigger_source,omitempty"`
StatusRepo string `json:"status_repo"`
StatusNumber string `json:"status_number"`
}
ExecutionRef is the matrix payload consumed by harness-run and fullsend run.
func Dispatch ¶
func Dispatch(ctx context.Context, opts Options) ([]ExecutionRef, error)
Dispatch evaluates authorization, kill switch, harness triggers, and returns execution refs. Returns empty slice (not error) when denied, kill-switched, or no triggers match. Returns an error when every registered harness fails to resolve or load.
func ProjectExecutionRef ¶
func ProjectExecutionRef(agentName string, role string, event *normevent.Event) (ExecutionRef, error)
ProjectExecutionRef maps a matched harness and event to an execution ref. Harness role values must be registered in the mint service ALLOWED_ROLES policy; custom role names pass harness validation but fail token minting with HTTP 403 until mint enrollment is extended for the repo.
type Options ¶
type Options struct {
// ConfigDir is the fullsend config directory (e.g. ".fullsend").
// Must be a direct child of the repo root; filepath.Dir is used
// to locate OWNERS and OWNERS_ALIASES for authorization.
ConfigDir string
Event *normevent.Event
// FetchPolicy controls SSRF protection for URL-sourced agent harnesses.
// When nil, fetch.DefaultPolicy is used (allows github.com and
// raw.githubusercontent.com). Set this in tests to allow httptest domains.
FetchPolicy *fetch.FetchPolicy
}
Options configures a dispatch run.
type TriggeredHarness ¶
TriggeredHarness pairs a registered agent with its loaded harness.
func FilterAuthorizedHarnesses ¶ added in v0.50.0
func FilterAuthorizedHarnesses(harnesses []TriggeredHarness, event *normevent.Event) []TriggeredHarness
FilterAuthorizedHarnesses returns the subset of harnesses that event is authorized to dispatch, keyed on each harness role: field. Run it before MatchHarnesses so CEL only evaluates authorized harnesses.
func FilterAuthorizedHarnessesWith ¶ added in v0.54.0
func FilterAuthorizedHarnessesWith(harnesses []TriggeredHarness, event *normevent.Event, opts AuthOptions) []TriggeredHarness
FilterAuthorizedHarnessesWith is FilterAuthorizedHarnesses under the policy in opts.
func ListTriggeredHarnesses ¶
func ListTriggeredHarnesses(ctx context.Context, configDir string, cfg config.ConfigReader, fetchPolicy *fetch.FetchPolicy) ([]TriggeredHarness, error)
ListTriggeredHarnesses returns config-registered agents whose harness has a non-empty trigger. fetchPolicy controls SSRF protection for URL-sourced agents. When nil, fetch.DefaultPolicy is used. Callers that need custom domain lists (e.g. tests using httptest) can pass a policy with the test server's domain.
Per-agent resolve/load failures are logged as GitHub Actions error annotations and skipped so a single broken harness does not block the rest. If every registered agent fails to resolve or load, an error is returned so a fully-unreadable harness set is not indistinguishable from "no trigger matched".
func MatchHarnesses ¶
func MatchHarnesses(candidates []TriggeredHarness, event *normevent.Event) ([]TriggeredHarness, error)
MatchHarnesses evaluates CEL triggers and returns matching harnesses.