githubscheduler

Documentation

Overview

Package githubscheduler implements the "github" scheduling backend: each scheduled job is materialized as a GitHub Actions scheduled workflow in a user-configured repository, deployed via pull requests. GitHub runs the jobs; nothing executes locally except the optional artifact poller.

Index

• Constants
• func RenderWorkflow(job *domain.ScheduledJob, ghCron, defaultModel string, ...) ([]byte, error)
• func ResolveRepo(ctx context.Context, runner CommandRunner, configured string) (string, error)
• func TranslateCron(expr string) (string, error)
• func WorkflowPath(jobID string) string
• type ArtifactPoller
  • func NewArtifactPoller(opts ArtifactPollerOptions) (*ArtifactPoller, error)
  • func (p *ArtifactPoller) Start(ctx context.Context) error
  • func (p *ArtifactPoller) Stop(ctx context.Context) error
• type ArtifactPollerOptions
• type CommandRunner
• type Store
  • func NewStore(inner storage.ScheduledJobStorage, runner CommandRunner, ...) *Store
  • func (s *Store) DeleteJob(ctx context.Context, id string) error
  • func (s *Store) LastPRURL() string
  • func (s *Store) ListJobs(ctx context.Context) ([]*domain.ScheduledJob, error)
  • func (s *Store) LoadJob(ctx context.Context, id string) (*domain.ScheduledJob, error)
  • func (s *Store) SaveJob(ctx context.Context, job *domain.ScheduledJob) error

Constants

const (
	// ArtifactNamePrefix is shared by the rendered upload step and the poller.
	ArtifactNamePrefix = "infer-conversations-"
)

const (
	// DefaultRepoName is the repository created under the authenticated user
	// when scheduler.github.repository is not configured.
	DefaultRepoName = ".routines"
)

Functions

func RenderWorkflow

func RenderWorkflow(job *domain.ScheduledJob, ghCron, defaultModel string, cfg config.SchedulerGitHubConfig) ([]byte, error)

RenderWorkflow renders one job's Actions workflow. ghCron must already be translated via TranslateCron; defaultModel is used when the job has none.

func ResolveRepo

func ResolveRepo(ctx context.Context, runner CommandRunner, configured string) (string, error)

ResolveRepo returns the configured repository, defaulting to "<authenticated user>/.routines".

func TranslateCron

func TranslateCron(expr string) (string, error)

TranslateCron converts a robfig/cron expression (including @descriptors and @every durations) into a GitHub Actions compatible 5-field UTC cron, or returns an error explaining why the expression cannot be scheduled on GitHub.

func WorkflowPath

func WorkflowPath(jobID string) string

WorkflowPath returns the repo-relative path of a job's workflow file.

Types

type ArtifactPoller

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

ArtifactPoller periodically downloads conversation artifacts uploaded by GitHub-backed job runs and drops their jsonl files into local conversation storage. Lifecycle mirrors the heartbeat service. ponytail: raw jsonl drop only works for storage.type jsonl; parse-and-save via ConversationStorage if sqlite/postgres users ask.

func NewArtifactPoller

func NewArtifactPoller(opts ArtifactPollerOptions) (*ArtifactPoller, error)

NewArtifactPoller validates options and constructs a poller.

func (*ArtifactPoller) Start

func (p *ArtifactPoller) Start(ctx context.Context) error

Start launches the ticker goroutine. Calling Start more than once is a no-op.

func (*ArtifactPoller) Stop

func (p *ArtifactPoller) Stop(ctx context.Context) error

Stop cancels the ticker and waits for an in-flight tick to finish.

type ArtifactPollerOptions

type ArtifactPollerOptions struct {
	Runner           CommandRunner
	Repo             string // "<owner>/<name>", already resolved
	ConversationsDir string // local dir jsonl files are extracted into
	ArtifactsDir     string // local dir non-jsonl files (images, reports) are extracted into; empty skips them
	StatePath        string // cursor/attempts persistence file
	Interval         time.Duration
	InitialDelay     time.Duration
	MaxAttempts      int           // per artifact; then skipped permanently
	RateLimitBackoff time.Duration // pause after a rate-limited API call
}

ArtifactPollerOptions bundles dependencies for NewArtifactPoller.

type CommandRunner

type CommandRunner interface {
	Run(ctx context.Context, name string, args ...string) ([]byte, error)
}

CommandRunner matches githubsetup.CommandRunner; redeclared locally so the poller can be constructed without importing githubsetup.

type Store

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

Store decorates a local ScheduledJobStorage: reads delegate to the local store (source of truth for the CLI), writes additionally render the job's Actions workflow and deploy it to the configured GitHub repository - pushed straight to the default branch, or via a PR when pull_requests is enabled. A failed GitHub sync aborts the local write, so no phantom jobs.

func NewStore

func NewStore(inner storage.ScheduledJobStorage, runner CommandRunner, cfg config.SchedulerGitHubConfig, defaultModel string) *Store

NewStore wraps inner with GitHub workflow sync. runner is typically &githubsetup.RealRunner{}.

func (*Store) DeleteJob

func (s *Store) DeleteJob(ctx context.Context, id string) error

DeleteJob removes the job's workflow from the repo (skipped when the file is absent), then deletes the job locally.

func (*Store) LastPRURL

func (s *Store) LastPRURL() string

LastPRURL returns the URL of the PR opened by the most recent successful SaveJob/DeleteJob, or "" when the last write needed no PR. The schedule tool type-asserts for this to surface the link to the user.

func (*Store) ListJobs

func (s *Store) ListJobs(ctx context.Context) ([]*domain.ScheduledJob, error)

ListJobs delegates to the local store.

func (*Store) LoadJob

func (s *Store) LoadJob(ctx context.Context, id string) (*domain.ScheduledJob, error)

LoadJob delegates to the local store.

func (*Store) SaveJob

func (s *Store) SaveJob(ctx context.Context, job *domain.ScheduledJob) error

SaveJob renders the job's workflow, deploys it to the repo, then persists the job locally. Validation failures and gh errors abort before the local save.