[codex] Add ephemeral GitHub runner job spec (#29)

* test: cover org github runner provider preflight

* feat: add org github runner provider lifecycle

* test: cover ephemeral github runner job operation

* feat: add ephemeral github runner job spec

* fix: enforce ephemeral runner timeouts

Author: intel352

.goreleaser.yaml

@@ -36,12 +36,26 @@ builds:
     goarch:
       - amd64
       - arm64
+  - id: github-actions-runner-job
+    main: ./cmd/github-actions-runner-job
+    binary: github-actions-runner-job
+    env:
+      - CGO_ENABLED=0
+      - GOPRIVATE=github.com/GoCodeAlone/*
+    goos:
+      - linux
+      - darwin
+      - windows
+    goarch:
+      - amd64
+      - arm64
 
 archives:
   - id: workflow-plugin-github
     ids:
       - workflow-plugin-github
       - github-runner-provider
+      - github-actions-runner-job
     name_template: "{{ .ProjectName }}-{{ .Os }}-{{ .Arch }}"
     files:
       - plugin.json

cmd/github-actions-runner-job/main.go

@@ -0,0 +1,41 @@
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+
+	"github.com/GoCodeAlone/workflow-plugin-github/internal"
+)
+
+func main() {
+	if err := run(); err != nil {
+		fmt.Fprintf(os.Stderr, "github-actions-runner-job failed: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func run() error {
+	specOnly := flag.Bool("spec", false, "emit the deterministic runner spec without starting a runner")
+	flag.Parse()
+	if !*specOnly {
+		return fmt.Errorf("runner execution is not available without a host-provided execution driver; use --spec only for preflight/spec generation")
+	}
+
+	var req internal.EphemeralRunnerJobRequest
+	decoder := json.NewDecoder(os.Stdin)
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&req); err != nil {
+		return fmt.Errorf("decode request: %w", err)
+	}
+	spec, err := internal.BuildEphemeralRunnerJobSpec(req)
+	if err != nil {
+		return err
+	}
+	return json.NewEncoder(os.Stdout).Encode(map[string]any{
+		"runner_name":  spec.RunnerName,
+		"labels":       spec.Labels,
+		"runner_group": spec.RunnerGroup,
+	})
+}

internal/ephemeral_runner_job.go

@@ -0,0 +1,189 @@
+package internal
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+)
+
+var ErrEphemeralRunnerCapabilityUnsupported = errors.New("ephemeral runner capability unsupported")
+
+const ephemeralRunnerCleanupTimeout = 30 * time.Second
+
+type EphemeralRunnerJobMode string
+
+const (
+	EphemeralRunnerJobModeDispatchThenWait EphemeralRunnerJobMode = "dispatch_then_wait"
+	EphemeralRunnerJobModeAttachToQueued   EphemeralRunnerJobMode = "attach_to_queued"
+)
+
+type EphemeralRunnerJobRequest struct {
+	Mode                EphemeralRunnerJobMode `json:"mode"`
+	Environment         string                 `json:"environment"`
+	OS                  string                 `json:"os"`
+	WorkerID            string                 `json:"worker_id"`
+	TaskID              string                 `json:"task_id"`
+	Organization        string                 `json:"organization"`
+	Repository          string                 `json:"repository,omitempty"`
+	Workflow            string                 `json:"workflow,omitempty"`
+	Ref                 string                 `json:"ref,omitempty"`
+	RunnerGroup         string                 `json:"runner_group,omitempty"`
+	Timeout             time.Duration          `json:"-"`
+	RequiredRuntimeCaps []string               `json:"required_runtime_caps,omitempty"`
+	AdvertisedCaps      []string               `json:"advertised_caps,omitempty"`
+}
+
+type EphemeralRunnerJobSpec struct {
+	RunnerName  string   `json:"runner_name"`
+	Labels      []string `json:"labels"`
+	RunnerGroup string   `json:"runner_group,omitempty"`
+}
+
+type EphemeralRunnerJobResult struct {
+	RunnerID      int64    `json:"runner_id"`
+	RunnerName    string   `json:"runner_name"`
+	Labels        []string `json:"labels"`
+	WorkflowRunID int64    `json:"workflow_run_id"`
+	WorkflowJobID int64    `json:"workflow_job_id"`
+	WorkerID      string   `json:"worker_id"`
+	TaskID        string   `json:"task_id"`
+	ArtifactRefs  []string `json:"artifact_refs"`
+	CleanupStatus string   `json:"cleanup_status"`
+	RedactedError string   `json:"redacted_error,omitempty"`
+}
+
+type EphemeralRunnerJobDriver interface {
+	OrgRegistrationToken(ctx context.Context, organization string) (GitHubRunnerRegistrationToken, error)
+	RunGitHubJob(ctx context.Context, mode EphemeralRunnerJobMode, spec EphemeralRunnerJobSpec, token GitHubRunnerRegistrationToken) (EphemeralRunnerJobResult, error)
+	RemoveOrgRunner(ctx context.Context, organization string, runnerID int64) error
+}
+
+type EphemeralRunnerJob struct {
+	driver EphemeralRunnerJobDriver
+}
+
+func NewEphemeralRunnerJob(driver EphemeralRunnerJobDriver) *EphemeralRunnerJob {
+	return &EphemeralRunnerJob{driver: driver}
+}
+
+func BuildEphemeralRunnerJobSpec(req EphemeralRunnerJobRequest) (EphemeralRunnerJobSpec, error) {
+	environment := strings.ToLower(strings.TrimSpace(req.Environment))
+	if environment == "" {
+		return EphemeralRunnerJobSpec{}, errors.New("environment is required")
+	}
+	osName := strings.ToLower(strings.TrimSpace(req.OS))
+	if osName == "" {
+		return EphemeralRunnerJobSpec{}, errors.New("os is required")
+	}
+	worker := shortEphemeralID(req.WorkerID)
+	if worker == "" {
+		return EphemeralRunnerJobSpec{}, errors.New("worker_id is required")
+	}
+	task := shortEphemeralID(req.TaskID)
+	if task == "" {
+		return EphemeralRunnerJobSpec{}, errors.New("task_id is required")
+	}
+	name := fmt.Sprintf("wfc-%s-ghp-%s-%s-%s", environment, osName, worker, task)
+	return EphemeralRunnerJobSpec{
+		RunnerName:  name,
+		RunnerGroup: strings.TrimSpace(req.RunnerGroup),
+		Labels: []string{
+			"self-hosted",
+			osName,
+			name,
+			"wfc-ghp-" + environment,
+			"wfc-ghp-ephemeral",
+		},
+	}, nil
+}
+
+func (j *EphemeralRunnerJob) Run(ctx context.Context, req EphemeralRunnerJobRequest) (EphemeralRunnerJobResult, error) {
+	if err := requireEphemeralRunnerCapabilities(req.RequiredRuntimeCaps, req.AdvertisedCaps); err != nil {
+		return EphemeralRunnerJobResult{}, err
+	}
+	if j == nil || j.driver == nil {
+		return EphemeralRunnerJobResult{}, errors.New("ephemeral runner job driver is required")
+	}
+	spec, err := BuildEphemeralRunnerJobSpec(req)
+	if err != nil {
+		return EphemeralRunnerJobResult{}, err
+	}
+	jobCtx := ctx
+	cancel := func() {}
+	if req.Timeout > 0 {
+		jobCtx, cancel = context.WithTimeout(ctx, req.Timeout)
+	}
+	defer cancel()
+	token, err := j.driver.OrgRegistrationToken(jobCtx, req.Organization)
+	if err != nil {
+		return EphemeralRunnerJobResult{}, err
+	}
+	result, runErr := j.driver.RunGitHubJob(jobCtx, req.Mode, spec, token)
+	if result.RunnerID > 0 {
+		cleanupCtx, cleanupCancel := context.WithTimeout(context.WithoutCancel(ctx), ephemeralRunnerCleanupTimeout)
+		defer cleanupCancel()
+		if err := j.driver.RemoveOrgRunner(cleanupCtx, req.Organization, result.RunnerID); err != nil {
+			result.CleanupStatus = "remove_failed"
+			if runErr == nil {
+				runErr = err
+			}
+		} else {
+			result.CleanupStatus = "removed"
+		}
+	} else if result.CleanupStatus == "" {
+		result.CleanupStatus = "skipped"
+	}
+	fillEphemeralRunnerResult(&result, req, spec)
+	return result, runErr
+}
+
+func fillEphemeralRunnerResult(result *EphemeralRunnerJobResult, req EphemeralRunnerJobRequest, spec EphemeralRunnerJobSpec) {
+	if result.RunnerName == "" {
+		result.RunnerName = spec.RunnerName
+	}
+	if len(result.Labels) == 0 {
+		result.Labels = append([]string(nil), spec.Labels...)
+	}
+	if result.WorkerID == "" {
+		result.WorkerID = req.WorkerID
+	}
+	if result.TaskID == "" {
+		result.TaskID = req.TaskID
+	}
+}
+
+func requireEphemeralRunnerCapabilities(required, advertised []string) error {
+	available := map[string]struct{}{}
+	for _, cap := range advertised {
+		cap = strings.ToLower(strings.TrimSpace(cap))
+		if cap != "" {
+			available[cap] = struct{}{}
+		}
+	}
+	for _, cap := range required {
+		cap = strings.ToLower(strings.TrimSpace(cap))
+		if cap == "" {
+			continue
+		}
+		if _, ok := available[cap]; !ok {
+			return fmt.Errorf("%w: %s", ErrEphemeralRunnerCapabilityUnsupported, cap)
+		}
+	}
+	return nil
+}
+
+func shortEphemeralID(value string) string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return ""
+	}
+	if _, suffix, ok := strings.Cut(value, "-"); ok && suffix != "" {
+		value = suffix
+	}
+	if len(value) > 8 {
+		return value[:8]
+	}
+	return value
+}