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 IsLifecycleCloseAuthorized(event *normevent.Event, harnessRole string) 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 IsLifecycleCloseAuthorized ¶ added in v0.50.0
IsLifecycleCloseAuthorized reports whether event is a GitHub pull_request_target close (merged or not) and harnessRole, the resolved harness role: of the agent being routed, is the retro role. Such an event is authorized for that harness whoever closed the pull request: the authorization contract's lifecycle-close exception, which the bash router applies by starting a retro for any closer. Like the label exception it ignores the actor; a caller checks it before IsAuthorized, which still denies these events. Unlike that exception it is scoped to one harness role, because any pull request author can close their own pull request, and every other harness keeps its ordinary threshold.
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.