@trebired/git-host 2.0.0 → 2.1.0

package/dist/{internal/core → core}/forge_actions.js

@@ -1,48 +1,16 @@
 import { randomUUID } from "node:crypto";
-import { spawn } from "node:child_process";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { GitHostError } from "#8974ac53d713";
-import { text } from "#sy81xkgkmoa0";
+import { GitHostError } from "../errors.js";
+import { text } from "../utils/text.js";
+import { executeActionsRunner, resolveActionsWorkspaceRoot } from "./actions_runner.js";
+import { listRepositoryWorkflows, readRepositoryWorkflow, resolveRepositoryWorkflowRoot } from "./actions_workflows.js";
 import { runGit } from "./run_git.js";
 const ACTIVITY_LISTENER_SYMBOL = Symbol.for("@trebired/git-host/actions-activity-listeners");
 const ACTIVITY_WRAPPED_SYMBOL = Symbol.for("@trebired/git-host/actions-activity-wrapped");
-const OUTPUT_PREVIEW_LIMIT = 4000;
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 1000;
 const TERMINAL_RUN_STATUSES = new Set(["cancelled", "failed", "skipped", "success"]);
 function nowIso() {
     return new Date().toISOString();
 }
-function slugify(value) {
-    const next = text(value)
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "");
-    return next || "workflow";
-}
-function normalizeEnv(value) {
-    if (!value || typeof value !== "object")
-        return undefined;
-    const next = Object.fromEntries(Object.entries(value)
-        .map(([key, entry]) => [text(key), text(entry)])
-        .filter(([key, entry]) => key && entry));
-    return Object.keys(next).length ? next : undefined;
-}
-function normalizeSteps(steps) {
-    return (Array.isArray(steps) ? steps : []).map((step) => ({
-        env: normalizeEnv(step.env),
-        id: text(step.id, randomUUID()),
-        kind: "shell",
-        name: text(step.name, "Step"),
-        run: text(step.run),
-        shell: text(step.shell),
-    })).filter((step) => step.run);
-}
-function appendOutputPreview(current, chunk) {
-    const next = `${current}${chunk}`;
-    return next.length <= OUTPUT_PREVIEW_LIMIT ? next : next.slice(-OUTPUT_PREVIEW_LIMIT);
-}
 function toDateSortValue(value) {
     return text(value);
 }
@@ -71,10 +39,10 @@ function ensureActionsStorage(storage) {
 function normalizeRunner(options) {
     const runner = options?.runner || {};
     return {
-        capabilities: Array.isArray(runner.capabilities) ? runner.capabilities.map((entry) => text(entry)).filter(Boolean) : ["shell", "snapshot", "streaming-logs"],
-        host: text(runner.host, os.hostname()),
-        id: text(runner.id, `local-${os.hostname()}`),
-        kind: text(runner.kind, "local-host"),
+        capabilities: Array.isArray(runner.capabilities) ? runner.capabilities.map((entry) => text(entry)).filter(Boolean) : ["go-runner", "shell", "snapshot", "streaming-logs"],
+        host: text(runner.host, "local-host"),
+        id: text(runner.id, "go-runner"),
+        kind: text(runner.kind, "go-runner"),
         platform_version: text(runner.platform_version, "@trebired/git-host"),
     };
 }
@@ -145,39 +113,6 @@ function createGitForgeActionsRuntime(options) {
             repositoryPath,
         };
     }
-    async function materializeRunWorkspace(run) {
-        const repositoryPath = await readRepositoryPath(run.repository_id);
-        const root = path.join(text(options.actions?.workspaceRoot, path.join(os.tmpdir(), "@trebired-git-host-actions")), text(run.repository_id), run.id);
-        const workspacePath = path.join(root, "workspace");
-        fs.rmSync(root, { force: true, recursive: true });
-        fs.mkdirSync(root, { recursive: true });
-        const cloneRes = await runGit(["clone", "--no-checkout", repositoryPath, workspacePath], { cwd: root });
-        if (!cloneRes.ok) {
-            throw new GitHostError("git_command_failed", text(cloneRes.stderr, "Failed to materialize workflow workspace."), {
-                repositoryId: run.repository_id,
-                runId: run.id,
-            });
-        }
-        const checkoutRes = await runGit(["checkout", "--detach", run.commit_hash], { cwd: workspacePath });
-        if (!checkoutRes.ok) {
-            throw new GitHostError("git_command_failed", text(checkoutRes.stderr, "Failed to check out workflow commit."), {
-                commitHash: run.commit_hash,
-                repositoryId: run.repository_id,
-                runId: run.id,
-            });
-        }
-        return workspacePath;
-    }
-    async function readRequiredWorkflow(repositoryId, workflowId) {
-        const workflow = await storage.readWorkflow(repositoryId, workflowId);
-        if (!workflow) {
-            throw new GitHostError("forge_resource_not_found", `Workflow "${workflowId}" was not found.`, {
-                repositoryId,
-                workflowId,
-            });
-        }
-        return workflow;
-    }
     async function readRequiredRun(repositoryId, runId) {
         const run = await storage.readWorkflowRun(repositoryId, runId);
         if (!run) {
@@ -240,125 +175,165 @@ function createGitForgeActionsRuntime(options) {
         });
         return finished;
     }
-    async function runShellStep(run, workflow, step, workspacePath) {
-        const active = activeRuns.get(run.id);
-        if (!active) {
-            throw new GitHostError("git_command_failed", "Workflow run is not active.", {
-                runId: run.id,
-            });
-        }
-        const startedStep = await updateRunStep(run.id, step.id, {
-            started_at: nowIso(),
-            status: "running",
+    async function readWorkflowAtRef(repositoryId, repositoryPath, ref, workflowId) {
+        const workflowRoot = await resolveRepositoryWorkflowRoot(options.actions, repositoryId);
+        return await readRepositoryWorkflow({
+            ref,
+            repositoryId,
+            repositoryPath,
+            workflowId,
+            workflowRoot,
         });
-        const updatedRun = await updateRun(run.repository_id, run.id, {
-            current_step: startedStep.name,
-            current_step_index: startedStep.index,
-            status: "running",
-            summary: `Running ${startedStep.name}.`,
+    }
+    async function queueWorkflowRun(repositoryId, workflow, input) {
+        const target = await resolveRunTarget(repositoryId, input);
+        const createdAt = nowIso();
+        const createdBy = text(input.actor.id, text(input.actor.name, "system"));
+        const run = await storage.createWorkflowRun({
+            branch: target.branch,
+            commit_hash: target.commitHash,
+            created_at: createdAt,
+            created_by: createdBy,
+            current_step: null,
+            current_step_index: null,
+            finished_at: null,
+            id: randomUUID(),
+            ref: target.ref,
+            release_id: input.releaseId == null ? null : text(input.releaseId),
+            repository_id: repositoryId,
+            runner: null,
+            started_at: null,
+            status: "queued",
+            summary: "Workflow run queued.",
+            trigger_context: {
+                ...(input.triggerContext || {}),
+                workflow_definition_path: workflow.definition_path,
+            },
+            trigger_kind: input.triggerKind,
+            workflow_id: workflow.id,
         });
-        await emitRunEvent(updatedRun, {
-            command: startedStep.command,
-            status: "running",
-            step_id: startedStep.id,
-            step_index: startedStep.index,
-            step_name: startedStep.name,
-            type: "step.started",
+        await Promise.all(workflow.steps.map(async (step, index) => {
+            await storage.createWorkflowRunStep({
+                command: step.run,
+                exit_code: null,
+                finished_at: null,
+                id: randomUUID(),
+                index,
+                kind: "shell",
+                metadata: step.env ? { env: step.env, shell: text(step.shell) } : (text(step.shell) ? { shell: text(step.shell) } : undefined),
+                name: text(step.name, `Step ${index + 1}`),
+                output_preview: "",
+                run_id: run.id,
+                started_at: null,
+                status: "queued",
+            });
+        }));
+        await emitRunEvent(run, {
+            metadata: {
+                branch: run.branch,
+                definition_path: workflow.definition_path,
+                ref: run.ref,
+            },
+            status: "queued",
+            summary: run.summary,
+            type: "run.accepted",
         });
-        let outputPreview = startedStep.output_preview;
-        const shell = text(workflow.steps[startedStep.index]?.shell, text(options.actions?.shell, "bash"));
-        const env = {
-            ...process.env,
-            ...(options.actions?.env || {}),
-            ...(workflow.env || {}),
-            ...(workflow.source?.env || {}),
-            ...(workflow.steps[startedStep.index]?.env || {}),
-            GIT_HOST_ACTIONS_REPOSITORY_ID: run.repository_id,
-            GIT_HOST_ACTIONS_RUN_ID: run.id,
-            GIT_HOST_ACTIONS_TRIGGER: text(run.trigger_kind),
-            GIT_HOST_ACTIONS_WORKFLOW_ID: workflow.id,
-            GIT_HOST_ACTIONS_COMMIT: run.commit_hash,
-            GIT_HOST_ACTIONS_REF: run.ref,
-            GIT_HOST_ACTIONS_BRANCH: text(run.branch),
-            GIT_HOST_ACTIONS_RELEASE_ID: text(run.release_id),
-        };
-        const child = spawn(shell, ["-lc", startedStep.command], {
-            cwd: workspacePath,
-            env,
-            stdio: ["ignore", "pipe", "pipe"],
+        queuedRuns.push({
+            repositoryId,
+            runId: run.id,
         });
-        active.child = child;
-        active.heartbeat = setInterval(() => {
-            void emitRunEvent(updatedRun, {
+        scheduleQueueProcessing();
+        return run;
+    }
+    async function handleRunnerEvent(run, stepsById, event) {
+        if (event.type === "run.status") {
+            const updatedRun = await updateRun(run.repository_id, run.id, {
+                status: event.status,
+                summary: text(event.summary, run.summary),
+            });
+            await emitRunEvent(updatedRun, {
+                status: updatedRun.status,
+                summary: updatedRun.summary,
+                type: "run.status",
+            });
+            return updatedRun;
+        }
+        const step = event.step_id ? stepsById.get(event.step_id) : undefined;
+        if (!step)
+            return run;
+        if (event.type === "step.started") {
+            const startedStep = await updateRunStep(run.id, step.id, {
+                started_at: nowIso(),
+                status: "running",
+            });
+            stepsById.set(step.id, startedStep);
+            const updatedRun = await updateRun(run.repository_id, run.id, {
+                current_step: startedStep.name,
+                current_step_index: startedStep.index,
+                status: "running",
+                summary: `Running ${startedStep.name}.`,
+            });
+            await emitRunEvent(updatedRun, {
+                command: text(event.command, startedStep.command),
                 status: "running",
                 step_id: startedStep.id,
                 step_index: startedStep.index,
                 step_name: startedStep.name,
-                type: "step.heartbeat",
+                type: "step.started",
             });
-        }, Math.max(250, Number(options.actions?.heartbeatIntervalMs) || DEFAULT_HEARTBEAT_INTERVAL_MS));
-        async function handleChunk(stream, chunk) {
-            let textChunk = typeof chunk === "string" ? chunk : chunk.toString("utf8");
-            if (options.actions?.redactOutput) {
-                textChunk = await options.actions.redactOutput({
-                    chunk: textChunk,
-                    run: updatedRun,
-                    step: startedStep,
-                    stream,
+            return updatedRun;
+        }
+        if (event.type === "step.output") {
+            let chunk = text(event.chunk);
+            if (chunk && options.actions?.redactOutput) {
+                chunk = await options.actions.redactOutput({
+                    chunk,
+                    run,
+                    step,
+                    stream: event.stream || "stdout",
                 });
             }
-            outputPreview = appendOutputPreview(outputPreview, textChunk);
-            await emitRunEvent(updatedRun, {
-                chunk: textChunk,
+            await emitRunEvent(run, {
+                chunk,
                 status: "running",
-                step_id: startedStep.id,
-                step_index: startedStep.index,
-                step_name: startedStep.name,
-                stream,
+                step_id: step.id,
+                step_index: step.index,
+                step_name: step.name,
+                stream: event.stream || "stdout",
                 type: "step.output",
             });
+            return run;
         }
-        const exitCode = await new Promise((resolve, reject) => {
-            child.stdout.on("data", (chunk) => {
-                void handleChunk("stdout", chunk);
-            });
-            child.stderr.on("data", (chunk) => {
-                void handleChunk("stderr", chunk);
+        if (event.type === "step.heartbeat") {
+            await emitRunEvent(run, {
+                status: "running",
+                step_id: step.id,
+                step_index: step.index,
+                step_name: step.name,
+                type: "step.heartbeat",
             });
-            child.on("error", reject);
-            child.on("close", (code) => resolve(Number(code) || 0));
-        });
-        if (active.heartbeat)
-            clearInterval(active.heartbeat);
-        active.child = undefined;
-        active.heartbeat = undefined;
-        const cancelled = active.cancelRequested === true;
-        const finalStatus = cancelled
-            ? "cancelled"
-            : (exitCode === 0 ? "success" : "failed");
-        const finishedStep = await updateRunStep(run.id, startedStep.id, {
-            exit_code: exitCode,
+            return run;
+        }
+        const finishedStep = await updateRunStep(run.id, step.id, {
+            exit_code: typeof event.exit_code === "number" ? event.exit_code : step.exit_code,
             finished_at: nowIso(),
-            output_preview: outputPreview,
-            status: finalStatus,
+            output_preview: text(event.output_preview, step.output_preview),
+            status: event.status || step.status,
         });
-        await emitRunEvent(updatedRun, {
+        stepsById.set(step.id, finishedStep);
+        await emitRunEvent(run, {
             command: finishedStep.command,
             metadata: {
-                exit_code: exitCode,
+                exit_code: finishedStep.exit_code,
             },
-            status: finalStatus,
+            status: finishedStep.status,
             step_id: finishedStep.id,
             step_index: finishedStep.index,
             step_name: finishedStep.name,
-            summary: finalStatus === "success" ? `${finishedStep.name} completed.` : `${finishedStep.name} ${cancelled ? "cancelled" : "failed"}.`,
+            summary: text(event.summary),
             type: "step.finished",
         });
-        return {
-            cancelled,
-            exitCode,
-            status: finalStatus,
-        };
+        return run;
     }
     async function executeRun(repositoryId, runId) {
         let run = await readRequiredRun(repositoryId, runId);
@@ -378,59 +353,64 @@ function createGitForgeActionsRuntime(options) {
             summary: run.summary,
             type: "run.status",
         });
-        const workflow = await readRequiredWorkflow(repositoryId, run.workflow_id);
+        const repositoryPath = await readRepositoryPath(repositoryId);
         const steps = await storage.listWorkflowRunSteps(run.id);
+        const stepsById = new Map(steps.map((step) => [step.id, step]));
         const activeState = {
             cancelRequested: false,
         };
         activeRuns.set(run.id, activeState);
         try {
-            activeState.workspacePath = await materializeRunWorkspace(run);
-            run = await updateRun(repositoryId, run.id, {
-                status: "running",
-                summary: "Workflow run started.",
-            });
-            await emitRunEvent(run, {
-                status: "running",
-                summary: run.summary,
-                type: "run.status",
+            const execution = executeActionsRunner({
+                actions: options.actions,
+                heartbeatIntervalMs: Math.max(250, Number(options.actions?.heartbeatIntervalMs) || DEFAULT_HEARTBEAT_INTERVAL_MS),
+                onEvent: async (event) => {
+                    run = await handleRunnerEvent(run, stepsById, event);
+                },
+                repositoryPath,
+                run,
+                steps,
+                workspaceRoot: resolveActionsWorkspaceRoot(options.actions, run.repository_id, run.id),
             });
-            for (const step of steps.sort((left, right) => left.index - right.index)) {
-                if (activeState.cancelRequested) {
-                    await markQueuedSteps(run.id, step.index - 1, "cancelled");
-                    return await finalizeRun(run, {
-                        eventType: "run.cancelled",
-                        status: "cancelled",
-                        summary: "Workflow run cancelled.",
-                    });
-                }
-                const result = await runShellStep(run, workflow, step, activeState.workspacePath);
-                if (result.cancelled) {
-                    await markQueuedSteps(run.id, step.index, "cancelled");
-                    return await finalizeRun(run, {
-                        eventType: "run.cancelled",
-                        status: "cancelled",
-                        summary: "Workflow run cancelled.",
-                    });
-                }
-                if (result.exitCode !== 0) {
-                    await markQueuedSteps(run.id, step.index, "skipped");
-                    return await finalizeRun(run, {
-                        eventType: "run.failed",
-                        status: "failed",
-                        summary: `Workflow run failed in step ${step.name}.`,
-                    });
-                }
+            activeState.child = execution.child;
+            const result = await execution.completed;
+            const persistedSteps = await storage.listWorkflowRunSteps(run.id);
+            const failedStep = persistedSteps.find((step) => step.status === "failed");
+            if (activeState.cancelRequested || result.cancelled) {
+                await markQueuedSteps(run.id, result.lastStepIndex, "cancelled");
+                return await finalizeRun(run, {
+                    currentStep: null,
+                    currentStepIndex: null,
+                    eventType: "run.cancelled",
+                    status: "cancelled",
+                    summary: "Workflow run cancelled.",
+                });
+            }
+            if (failedStep || result.exitCode !== 0) {
+                await markQueuedSteps(run.id, failedStep ? failedStep.index : result.lastStepIndex, "skipped");
+                return await finalizeRun(run, {
+                    currentStep: null,
+                    currentStepIndex: null,
+                    eventType: "run.failed",
+                    status: "failed",
+                    summary: failedStep
+                        ? `Workflow run failed in step ${failedStep.name}.`
+                        : `Workflow run failed in step ${text(result.lastStepName, "unknown")}.`,
+                });
             }
             return await finalizeRun(run, {
+                currentStep: null,
+                currentStepIndex: null,
                 eventType: "run.finished",
                 status: "success",
                 summary: "Workflow run completed successfully.",
             });
         }
         catch (error) {
-            await markQueuedSteps(run.id, -1, "skipped");
+            await markQueuedSteps(run.id, -1, activeState.cancelRequested ? "cancelled" : "skipped");
             return await finalizeRun(run, {
+                currentStep: null,
+                currentStepIndex: null,
                 eventType: activeState.cancelRequested ? "run.cancelled" : "run.failed",
                 status: activeState.cancelRequested ? "cancelled" : "failed",
                 summary: activeState.cancelRequested
@@ -439,8 +419,6 @@ function createGitForgeActionsRuntime(options) {
             });
         }
         finally {
-            if (activeState.heartbeat)
-                clearInterval(activeState.heartbeat);
             if (activeState.child && !activeState.child.killed) {
                 try {
                     activeState.child.kill("SIGKILL");
@@ -469,66 +447,22 @@ function createGitForgeActionsRuntime(options) {
             processing = false;
         }
     }
-    async function queueWorkflowRun(repositoryId, workflow, input) {
-        const target = await resolveRunTarget(repositoryId, input);
-        const createdAt = nowIso();
-        const createdBy = text(input.actor.id, text(input.actor.name, "system"));
-        const run = await storage.createWorkflowRun({
-            branch: target.branch,
-            commit_hash: target.commitHash,
-            created_at: createdAt,
-            created_by: createdBy,
-            current_step: null,
-            current_step_index: null,
-            finished_at: null,
-            id: randomUUID(),
-            ref: target.ref,
-            release_id: input.releaseId == null ? null : text(input.releaseId),
-            repository_id: repositoryId,
-            runner: null,
-            started_at: null,
-            status: "queued",
-            summary: "Workflow run queued.",
-            trigger_context: input.triggerContext,
-            trigger_kind: input.triggerKind,
-            workflow_id: workflow.id,
+    async function enqueueWorkflowsForTrigger(repositoryId, triggerKind, actor, context) {
+        const target = await resolveRunTarget(repositoryId, {
+            branch: text(context.branch),
+            commitHash: text(context.commit_hash, text(context.head_commit)),
+            ref: text(context.ref, text(context.tag_name, text(context.branch, "HEAD"))),
         });
-        await Promise.all(workflow.steps.map(async (step, index) => {
-            await storage.createWorkflowRunStep({
-                command: step.run,
-                exit_code: null,
-                finished_at: null,
-                id: randomUUID(),
-                index,
-                kind: "shell",
-                metadata: step.env ? { env: step.env, shell: text(step.shell) } : (text(step.shell) ? { shell: text(step.shell) } : undefined),
-                name: text(step.name, `Step ${index + 1}`),
-                output_preview: "",
-                run_id: run.id,
-                started_at: null,
-                status: "queued",
-            });
-        }));
-        await emitRunEvent(run, {
-            metadata: {
-                branch: run.branch,
-                ref: run.ref,
+        const workflowRoot = await resolveRepositoryWorkflowRoot(options.actions, repositoryId);
+        const workflows = await listRepositoryWorkflows({
+            filters: {
+                enabled: true,
+                trigger: triggerKind,
             },
-            status: "queued",
-            summary: run.summary,
-            type: "run.accepted",
-        });
-        queuedRuns.push({
+            ref: target.ref,
             repositoryId,
-            runId: run.id,
-        });
-        scheduleQueueProcessing();
-        return run;
-    }
-    async function enqueueWorkflowsForTrigger(repositoryId, triggerKind, actor, context) {
-        const workflows = await storage.listWorkflows(repositoryId, {
-            enabled: true,
-            trigger: triggerKind,
+            repositoryPath: target.repositoryPath,
+            workflowRoot,
         });
         const createdRuns = [];
         for (const workflow of workflows) {
@@ -536,9 +470,9 @@ function createGitForgeActionsRuntime(options) {
                 continue;
             createdRuns.push(await queueWorkflowRun(repositoryId, workflow, {
                 actor,
-                branch: text(context.branch),
-                commitHash: text(context.commit_hash, text(context.head_commit)),
-                ref: text(context.ref, text(context.tag_name, text(context.branch, "HEAD"))),
+                branch: target.branch || undefined,
+                commitHash: target.commitHash,
+                ref: target.ref,
                 releaseId: text(context.release_id) || null,
                 triggerContext: context,
                 triggerKind,
@@ -600,66 +534,28 @@ function createGitForgeActionsRuntime(options) {
     }
     return {
         bindActivityStorage,
-        async createWorkflow(repositoryId, input) {
-            const workflow = await storage.createWorkflow({
-                created_at: nowIso(),
-                created_by: text(input.actor.id),
-                enabled: input.enabled !== false,
-                env: normalizeEnv(input.env),
-                id: randomUUID(),
-                name: text(input.name),
-                repository_id: repositoryId,
-                slug: text(input.slug, slugify(input.name)),
-                source: input.source ? {
-                    branches: Array.isArray(input.source.branches) ? input.source.branches.map((entry) => text(entry)).filter(Boolean) : undefined,
-                    env: normalizeEnv(input.source.env),
-                    tags: Array.isArray(input.source.tags) ? input.source.tags.map((entry) => text(entry)).filter(Boolean) : undefined,
-                } : undefined,
-                steps: normalizeSteps(input.steps),
-                trigger: text(input.trigger),
-                updated_at: nowIso(),
-                updated_by: text(input.actor.id),
-            });
-            return workflow;
-        },
-        async updateWorkflow(repositoryId, workflowId, input) {
-            const current = await readRequiredWorkflow(repositoryId, workflowId);
-            const updated = await storage.updateWorkflow(repositoryId, workflowId, {
-                ...(input.enabled != null ? { enabled: input.enabled === true } : {}),
-                ...(input.env !== undefined ? { env: normalizeEnv(input.env) } : {}),
-                ...(input.name !== undefined ? { name: text(input.name) } : {}),
-                ...(input.slug !== undefined ? { slug: text(input.slug, current.slug) } : {}),
-                ...(input.source !== undefined ? {
-                    source: {
-                        branches: Array.isArray(input.source?.branches) ? input.source?.branches.map((entry) => text(entry)).filter(Boolean) : undefined,
-                        env: normalizeEnv(input.source?.env),
-                        tags: Array.isArray(input.source?.tags) ? input.source?.tags.map((entry) => text(entry)).filter(Boolean) : undefined,
-                    },
-                } : {}),
-                ...(input.steps !== undefined ? { steps: normalizeSteps(input.steps) } : {}),
-                ...(input.trigger !== undefined ? { trigger: text(input.trigger) } : {}),
-                updated_at: nowIso(),
-                updated_by: text(input.actor.id),
-            });
-            if (!updated) {
-                throw new GitHostError("forge_resource_not_found", `Workflow "${workflowId}" was not found.`, {
-                    repositoryId,
-                    workflowId,
-                });
-            }
-            return updated;
-        },
         async listWorkflows(repositoryId, filters) {
-            const entries = await storage.listWorkflows(repositoryId, filters);
-            return Array.from(entries).sort((left, right) => text(left.name).localeCompare(text(right.name)) || text(left.slug).localeCompare(text(right.slug)));
+            const repositoryPath = await readRepositoryPath(repositoryId);
+            const workflowRoot = await resolveRepositoryWorkflowRoot(options.actions, repositoryId);
+            return await listRepositoryWorkflows({
+                filters,
+                repositoryId,
+                repositoryPath,
+                workflowRoot,
+            });
         },
         async readWorkflow(repositoryId, workflowId) {
-            return await readRequiredWorkflow(repositoryId, workflowId);
+            const repositoryPath = await readRepositoryPath(repositoryId);
+            return await readWorkflowAtRef(repositoryId, repositoryPath, undefined, workflowId);
         },
         async runWorkflow(repositoryId, workflowId, input) {
-            const workflow = await readRequiredWorkflow(repositoryId, workflowId);
+            const target = await resolveRunTarget(repositoryId, input);
+            const workflow = await readWorkflowAtRef(repositoryId, target.repositoryPath, target.ref, workflowId);
             return await queueWorkflowRun(repositoryId, workflow, {
                 ...input,
+                branch: target.branch || undefined,
+                commitHash: target.commitHash,
+                ref: target.ref,
                 triggerKind: "manual",
             });
         },
@@ -707,8 +603,7 @@ function createGitForgeActionsRuntime(options) {
             return await storage.listWorkflowRunEvents(runId, filters);
         },
         subscribeWorkflowRun(repositoryId, runId, listener) {
-            const key = `${repositoryId}:${runId}`;
-            void key;
+            void repositoryId;
             let listeners = runListeners.get(runId);
             if (!listeners) {
                 listeners = new Set();