forgejo

Documentation

Overview

Package forgejo implements providers.Provider for Forgejo Actions.

Forgejo Actions uses the same workflow syntax as GitHub Actions but runs jobs via forgejo-runner, a hard fork of Gitea's act_runner. The runner binary embeds a fork of nektos/act and talks to the Forgejo instance over ConnectRPC (Register, Declare, FetchTask, UpdateTask, UpdateLog).

Integration model (embed binary):

ephemerd polls for tasks via the ConnectRPC FetchTask endpoint.
When a job arrives, ephemerd spins up a container from the default
runner image (which has forgejo-runner pre-installed) and launches:

  forgejo-runner one-job \
    --url <instance_url> \
    --token-url file:///run/secrets/token \
    --label <labels> \
    --handle <task-uuid>

The runner handles workflow execution, log streaming, and status
reporting. ephemerd manages the container lifecycle.

Reference:

• Runner source: https://code.forgejo.org/forgejo/runner
• Runner proto: https://code.forgejo.org/forgejo/actions-proto
• API docs: https://forgejo.org/docs/next/user/actions/

Index

• type Config
• type Provider
  • func New(cfg Config) (*Provider, error)
  • func (p *Provider) ClaimJob(ctx context.Context, event *providers.JobEvent, runnerName string, ...) (*providers.Claim, error)
  • func (p *Provider) DefaultImage() string
  • func (p *Provider) DefaultImageFor(os string) string
  • func (p *Provider) DefaultJobImage() string
  • func (p *Provider) FetchJobImage(ctx context.Context, event *providers.JobEvent) string
  • func (p *Provider) Name() string
  • func (p *Provider) ReleaseJob(ctx context.Context, claim *providers.Claim) error
  • func (p *Provider) Start(ctx context.Context, cfg providers.PollConfig) (<-chan providers.JobEvent, error)
  • func (p *Provider) Stop(ctx context.Context) error

Types

type Config

type Config struct {
	// InstanceURL is the base URL of the Forgejo instance (e.g., "https://codeberg.org").
	InstanceURL string

	// Token is the runner registration token from the Forgejo admin panel.
	// Found at: Site Administration > Actions > Runners > Create new runner.
	Token string

	// Owner is the organization or user that owns the runner.
	// If empty, the runner is registered at the instance level.
	Owner string

	// Repos limits the runner to specific repositories.
	// If empty, the runner accepts jobs from all repos the owner has access to.
	Repos []string

	// Labels are the runner labels to register with the forge.
	// Each label is a string like "ubuntu-latest:docker://image:tag".
	// If empty, defaults to ["ubuntu-latest:docker://<job_image>"].
	Labels []string

	// DefaultImage is the legacy single-image override for the runner
	// daemon container (Linux). Prefer LinuxImage / WindowsImage. Kept for
	// backward compatibility — when LinuxImage is empty, this is used as
	// the Linux default.
	// Default: "data.forgejo.org/forgejo/runner:12"
	DefaultImage string

	// LinuxImage / WindowsImage override the runner daemon image per job
	// OS. Forgejo's daemon is Linux-only upstream, but WindowsImage is
	// honored for callers that ship a custom build.
	LinuxImage   string
	WindowsImage string

	// JobImage is the default OCI image for job execution containers.
	// The runner daemon creates job containers via the fake Docker socket;
	// this image is what those containers run.
	// Default: "docker.io/gitea/runner-images:ubuntu-24.04"
	JobImage string

	// HTTPClient is an optional *http.Client for the ConnectRPC client.
	// If nil, a default client with 30s timeout is used.
	HTTPClient *http.Client

	Log *slog.Logger
}

Config for the Forgejo provider.

type Provider

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

Provider implements providers.Provider for Forgejo Actions.

func New

func New(cfg Config) (*Provider, error)

New creates a Forgejo provider.

func (*Provider) ClaimJob

func (p *Provider) ClaimJob(ctx context.Context, event *providers.JobEvent, runnerName string, labels []string) (*providers.Claim, error)

func (*Provider) DefaultImage

func (p *Provider) DefaultImage() string

func (*Provider) DefaultImageFor

func (p *Provider) DefaultImageFor(os string) string

DefaultImageFor returns the runner-daemon image for the given job OS. Forgejo's runner is Linux-only upstream; if a Windows override is set in config (cfg.WindowsImage) we honor it for completeness, otherwise return "" so the runtime picks its host fallback.

func (*Provider) DefaultJobImage

func (p *Provider) DefaultJobImage() string

func (*Provider) FetchJobImage

func (p *Provider) FetchJobImage(ctx context.Context, event *providers.JobEvent) string

func (*Provider) Name

func (p *Provider) Name() string

func (*Provider) ReleaseJob

func (p *Provider) ReleaseJob(ctx context.Context, claim *providers.Claim) error

func (*Provider) Start

func (p *Provider) Start(ctx context.Context, cfg providers.PollConfig) (<-chan providers.JobEvent, error)

func (*Provider) Stop

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