@secureci/cli 1.0.1 → 1.2.0

package/dist/parser/pipeline-contract-validator.js

@@ -43,6 +43,7 @@ const repository_1 = require("../utils/repository");
 const action_fetcher_1 = require("../runner/action-fetcher");
 const github_lockfile_1 = require("../github-lockfile");
 const permissions_1 = require("./permissions");
+const expression_1 = require("../runner/expression");
 /** Maximum nesting of composite actions / reusable workflows. */
 const MAX_DEPTH = 10;
 /**
@@ -81,8 +82,17 @@ async function validatePipelineContract(parsed, spec, options = {}) {
     (spec.required ?? []).forEach((entry, idx) => {
         const path = `required[${idx}]`;
         const name = normalizeActionName(entry.uses);
-        const candidates = sequence.filter((u) => u.name === name);
-        if (candidates.length > 0 && candidates.every((c) => c.conditional)) {
+        const found = sequence.filter((u) => u.name === name);
+        const candidates = found.filter((u) => u.runs !== 'never');
+        if (found.length > 0 && candidates.length === 0) {
+            errors.push({
+                path,
+                message: `Required action "${entry.uses}" never runs: its if: conditions (on its step or job) can't be true for this workflow's triggers (${(graph.events ?? []).join(', ')})`,
+                severity: 'error'
+            });
+            return;
+        }
+        if (candidates.length > 0 && candidates.every((c) => c.runs === 'maybe')) {
             errors.push({
                 path,
                 message: `Required action "${entry.uses}" only runs under an if: condition (on its step or job), so it may be skipped`,
@@ -275,6 +285,20 @@ function needsTransitively(nodes, from, to) {
 async function buildGraph(parsed, recurse, offline) {
     const graph = { sequence: [], nodes: new Map(), errors: [] };
     const root = (0, repository_1.repositoryRoot)(parsed.path);
+    // `if:` conditions are decided, where they can be, for each trigger of
+    // the workflow (called workflows run with their caller's event). With
+    // workflow_call, the event is the caller's, so it isn't known.
+    graph.events = triggerEvents(parsed.file.on);
+    const known = graph.events
+        ? graph.events.map((event) => triggerFacts(parsed.file.on, event))
+        : [{}];
+    /** `runs`, narrowed by a job or step's own `if:`. */
+    const within = (runs, condition) => runs.map((outer, i) => {
+        const own = (0, expression_1.staticCondition)(condition, known[i]);
+        if (outer === false || own === false)
+            return false;
+        return outer === true && own === true ? true : undefined;
+    });
     const isLocal = (uses) => uses.startsWith('./') || uses.startsWith('../');
     /**
      * The file behind a composite action / reusable workflow reference, or
@@ -355,31 +379,35 @@ async function buildGraph(parsed, recurse, offline) {
         }
         return true;
     };
-    const addUsage = (node, index, at, uses, conditional) => {
+    const addUsage = (node, index, at, uses, runs) => {
         graph.sequence.push({
             node,
             index,
             path: at,
-            conditional,
+            runs: runs.every((r) => r === false)
+                ? 'never'
+                : runs.every((r) => r === true)
+                    ? 'always'
+                    : 'maybe',
             ...splitActionRef(uses)
         });
     };
     /** Flatten a job's steps (and composite action steps) into `node`. */
-    const addSteps = async (steps, node, at, counter, stack, workflowRoot, conditional) => {
+    const addSteps = async (steps, node, at, counter, stack, workflowRoot, runs) => {
         for (const [i, step] of steps.entries()) {
             const stepPath = `${at}steps[${i}]`;
             if (!step.uses) {
                 counter.next++;
                 continue;
             }
-            const stepConditional = conditional || hasCondition(step.if);
-            addUsage(node, counter.next++, stepPath, step.uses, stepConditional);
+            const stepRuns = within(runs, step.if);
+            addUsage(node, counter.next++, stepPath, step.uses, stepRuns);
             const file = await resolveRef(step.uses, 'action', workflowRoot, stepPath);
             if (!file || !canEnter(file, stack, stepPath))
                 continue;
             const action = parse(file, stepPath);
             if (action?.type === 'action' && action.file.runs.using === 'composite') {
-                await addSteps(action.file.runs.steps ?? [], node, `${stepPath} > ${step.uses} > `, counter, [...stack, file], workflowRoot, stepConditional);
+                await addSteps(action.file.runs.steps ?? [], node, `${stepPath} > ${step.uses} > `, counter, [...stack, file], workflowRoot, stepRuns);
             }
         }
     };
@@ -388,7 +416,7 @@ async function buildGraph(parsed, recurse, offline) {
      * reusable-workflow call itself needs, plus the call). Returns the ids
      * of the added jobs.
      */
-    const addWorkflow = async (workflow, workflowRoot, prefix, labelPrefix, at, after, stack, conditional) => {
+    const addWorkflow = async (workflow, workflowRoot, prefix, labelPrefix, at, after, stack, runs) => {
         const added = [];
         // A job id -> the graph nodes standing for it (a reusable-workflow call
         // stands for the call and all of its called jobs).
@@ -408,17 +436,17 @@ async function buildGraph(parsed, recurse, offline) {
             });
             added.push(node);
             const jobPath = `${at}jobs.${jobId}`;
-            const jobConditional = conditional || hasCondition(job.if);
+            const jobRuns = within(runs, job.if);
             if (job.uses) {
                 // The call itself is a one-step "job" its called jobs run after.
-                addUsage(node, 0, jobPath, job.uses, jobConditional);
+                addUsage(node, 0, jobPath, job.uses, jobRuns);
                 graph.nodes.get(node).length = 1;
                 const ids = [node];
                 const file = await resolveRef(job.uses, 'workflow', workflowRoot, jobPath);
                 if (file && canEnter(file, stack, jobPath)) {
                     const called = parse(file, jobPath);
                     if (called?.type === 'workflow') {
-                        ids.push(...(await addWorkflow(called.file, (0, repository_1.repositoryRoot)(file), `${node}>`, `${labelPrefix}${jobId} > ${job.uses} > `, `${jobPath} > ${job.uses} > `, [...needs, node], [...stack, file], jobConditional)));
+                        ids.push(...(await addWorkflow(called.file, (0, repository_1.repositoryRoot)(file), `${node}>`, `${labelPrefix}${jobId} > ${job.uses} > `, `${jobPath} > ${job.uses} > `, [...needs, node], [...stack, file], jobRuns)));
                     }
                 }
                 alias.set(jobId, ids);
@@ -427,27 +455,127 @@ async function buildGraph(parsed, recurse, offline) {
             }
             alias.set(jobId, [node]);
             const counter = { next: 0 };
-            await addSteps(job.steps ?? [], node, `${jobPath}.`, counter, stack, workflowRoot, jobConditional);
+            await addSteps(job.steps ?? [], node, `${jobPath}.`, counter, stack, workflowRoot, jobRuns);
             graph.nodes.get(node).length = counter.next;
         }
         return added;
     };
-    await addWorkflow(parsed.file, root, '', '', '', [], [path.resolve(parsed.path)], false);
+    await addWorkflow(parsed.file, root, '', '', '', [], [path.resolve(parsed.path)], known.map(() => true));
     return graph;
 }
 /**
- * Whether an `if:` can skip the step/job: anything but a missing value,
- * `true`, `success()` (the default) or `always()`.
+ * The events that trigger a workflow (`on:` as a string, list or map), or
+ * undefined when the event isn't known: none are listed, or the workflow
+ * is reusable (it runs with its caller's event).
  */
-function hasCondition(condition) {
-    if (condition === undefined || condition === null || condition === true) {
-        return false;
+function triggerEvents(on) {
+    const events = typeof on === 'string'
+        ? [on]
+        : Array.isArray(on)
+            ? on.map(String)
+            : on && typeof on === 'object'
+                ? Object.keys(on)
+                : [];
+    return events.length === 0 || events.includes('workflow_call')
+        ? undefined
+        : events;
+}
+/** Characters that make a branch/tag filter pattern a glob. */
+const GLOB_CHARS = /[*?+[\]]/;
+/** The literal text a filter pattern starts with (before any glob). */
+function literalStart(pattern) {
+    const at = pattern.search(GLOB_CHARS);
+    return at === -1 ? pattern : pattern.slice(0, at);
+}
+/** Longest common prefix of `values` ('' for none). */
+function commonPrefix(values) {
+    if (values.length === 0)
+        return '';
+    let prefix = values[0];
+    for (const value of values.slice(1)) {
+        while (!value.startsWith(prefix))
+            prefix = prefix.slice(0, -1);
     }
-    const text = String(condition)
-        .trim()
-        .replace(/^\$\{\{([\s\S]*)\}\}$/, '$1')
-        .trim();
-    return !['', 'true', 'success()', 'always()'].includes(text);
+    return prefix;
+}
+/**
+ * `github.ref` / `github.ref_name` for a ref under `kind` (`refs/heads/`
+ * or `refs/tags/`) matching the positive `patterns`: exact for a single
+ * literal pattern, else known by prefix. `!negations` only narrow further.
+ */
+function refFromPatterns(kind, patterns) {
+    const positive = (Array.isArray(patterns) ? patterns : [])
+        .map(String)
+        .filter((p) => !p.startsWith('!'));
+    if (positive.length === 1 && !GLOB_CHARS.test(positive[0])) {
+        return { ref: kind + positive[0], ref_name: positive[0] };
+    }
+    const start = commonPrefix(positive.map(literalStart));
+    return { ref: (0, expression_1.knownPrefix)(kind + start), ref_name: (0, expression_1.knownPrefix)(start) };
+}
+/**
+ * What a workflow's `on.<event>` filters tell about `github.ref`: a push
+ * filtered only by branches (or only by tags) runs only for those refs;
+ * pull_request runs on `refs/pull/<n>/merge`; pull_request_target on the
+ * base branch, which its `branches:` filter matches. Unfiltered pushes and
+ * other events leave the ref unknown.
+ */
+function refFacts(event, config) {
+    const filters = config && typeof config === 'object' && !Array.isArray(config)
+        ? config
+        : {};
+    const has = (key) => key in filters;
+    const branchFilter = has('branches') || has('branches-ignore');
+    const tagFilter = has('tags') || has('tags-ignore');
+    if (event === 'push') {
+        if (branchFilter && !tagFilter) {
+            return refFromPatterns('refs/heads/', filters.branches);
+        }
+        if (tagFilter && !branchFilter) {
+            return refFromPatterns('refs/tags/', filters.tags);
+        }
+        return {};
+    }
+    if (event === 'pull_request')
+        return { ref: (0, expression_1.knownPrefix)('refs/pull/') };
+    if (event === 'pull_request_target') {
+        return refFromPatterns('refs/heads/', filters.branches);
+    }
+    return {};
+}
+/**
+ * What's known about one trigger of a workflow for static `if:` checks:
+ * `github.event_name`, `github.ref` / `ref_name` where its filters pin
+ * them, and `inputs.*`. Inputs are empty on events other than
+ * workflow_dispatch, so a declared dispatch input is null there; on
+ * workflow_dispatch only a choice with a single option is known (a
+ * `default` can be overridden by whoever dispatches).
+ */
+function triggerFacts(on, event) {
+    const config = on && typeof on === 'object' && !Array.isArray(on)
+        ? on[event]
+        : undefined;
+    const dispatch = on && typeof on === 'object' && !Array.isArray(on)
+        ? on
+            .workflow_dispatch
+        : undefined;
+    const declared = Object.entries(dispatch?.inputs ?? {});
+    const inputs = {};
+    for (const [name, spec] of declared) {
+        const input = (spec ?? {});
+        if (event !== 'workflow_dispatch') {
+            inputs[name] = null;
+        }
+        else if (input.type === 'choice' &&
+            Array.isArray(input.options) &&
+            input.options.length === 1) {
+            inputs[name] = String(input.options[0]);
+        }
+    }
+    return {
+        github: { event_name: event, ...refFacts(event, config) },
+        ...(declared.length > 0 ? { inputs } : {})
+    };
 }
 function splitActionRef(uses) {
     const atIndex = uses.lastIndexOf('@');

package/dist/runner/action-fetcher.js

@@ -43,6 +43,7 @@ exports.lsRemoteSha = lsRemoteSha;
 exports.parseLsRemoteTags = parseLsRemoteTags;
 exports.lsRemoteTags = lsRemoteTags;
 exports.getText = getText;
+exports.getResponse = getResponse;
 exports.followRedirect = followRedirect;
 exports.fetchAction = fetchAction;
 exports.fetchRepoFile = fetchRepoFile;
@@ -222,6 +223,10 @@ async function lsRemoteTags(url) {
  * with an error carrying `status`.
  */
 function getText(url, headers, timeoutMs) {
+    return getResponse(url, headers, timeoutMs).then((r) => r.body);
+}
+/** getText, with the response headers (e.g. `link` for pagination). */
+function getResponse(url, headers, timeoutMs) {
     return new Promise((resolve, reject) => {
         const client = url.startsWith('http://') ? http : https;
         const request = client.get(url, { headers }, (response) => {
@@ -237,7 +242,7 @@ function getText(url, headers, timeoutMs) {
                 body += chunk;
             });
             response.on('end', () => response.statusCode === 200
-                ? resolve(body)
+                ? resolve({ body, headers: response.headers })
                 : reject(Object.assign(new Error(`HTTP ${response.statusCode}`), {
                     status: response.statusCode
                 })));

package/dist/runner/actions.js

@@ -93,7 +93,7 @@ function warnUnsandboxedActions(steps, ctx, options) {
 async function stepFileSystem(runtime) {
     const container = runtime.container;
     if (!container)
-        return (0, builtin_actions_1.hostFileSystem)(process.cwd());
+        return (0, builtin_actions_1.hostFileSystem)(runtime.workspace);
     if (container.home === undefined) {
         const probe = await container.runtime.exec(container.id, {
             command: 'printf %s "$HOME"'
@@ -102,7 +102,7 @@ async function stepFileSystem(runtime) {
     }
     return (0, builtin_actions_1.containerFileSystem)({
         workspace: container_runtime_1.CONTAINER_WORKDIR,
-        hostWorkspace: process.cwd(),
+        hostWorkspace: runtime.workspace,
         home: container.home,
         copyFrom: (from, to) => container.runtime.copyFrom(container.id, from, to),
         copyTo: (from, to) => container.runtime.copyTo(container.id, from, to),
@@ -259,8 +259,8 @@ function isLocalActionRef(uses) {
  * Resolve a local action (`uses: ./path/to/action`) relative to the
  * workspace, like the runner does, to its action.yml / action.yaml.
  */
-function resolveLocalAction(uses) {
-    const dir = path.resolve(process.cwd(), uses);
+function resolveLocalAction(uses, workspace = process.cwd()) {
+    const dir = path.resolve(workspace, uses);
     for (const name of ['action.yml', 'action.yaml']) {
         const candidate = path.join(dir, name);
         if (fs.existsSync(candidate))
@@ -297,22 +297,24 @@ async function executeAction(step, options, startTime, runtime, ctx) {
                     args: withValues.args ? (0, shell_1.splitArgs)(withValues.args) : []
                 }
             };
-            return await (0, docker_action_1.executeDockerAction)(dockerAction, path.join(process.cwd(), 'action.yml'), step, {}, callerCtx.env, options, runtime, startTime);
+            return await (0, docker_action_1.executeDockerAction)(dockerAction, path.join(runtime.workspace, 'action.yml'), step, {}, callerCtx.env, options, runtime, startTime);
         }
         if (options.localCheckout !== false &&
             (0, checkout_1.isLocalCheckout)(step.uses, step.with, callerCtx)) {
-            return (0, checkout_1.localCheckout)(step, callerCtx, runtime, startTime);
+            return (0, checkout_1.localCheckout)(step, callerCtx, runtime, startTime, {
+                fetchRefs: options.fetchRefs
+            });
         }
         const builtin = (0, builtin_actions_1.builtinActionFor)(step.uses);
         if (builtin) {
             return await runBuiltinAction(builtin, step, callerCtx, options, runtime, startTime);
         }
         const actionPath = isLocalActionRef(step.uses)
-            ? resolveLocalAction(step.uses)
+            ? resolveLocalAction(step.uses, runtime.workspace)
             : await fetchActionOnce(step.uses, options, runtime);
         if (!actionPath) {
             const error = `Could not resolve action "${step.uses}"${isLocalActionRef(step.uses)
-                ? ` (no action.yml or action.yaml in ${path.resolve(process.cwd(), step.uses)})`
+                ? ` (no action.yml or action.yaml in ${path.resolve(runtime.workspace, step.uses)})`
                 : ''}`;
             logger_1.logger.error(error);
             return {

package/dist/runner/checkout.js

@@ -34,12 +34,18 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.copyWorkingCopy = copyWorkingCopy;
+exports.createIsolatedWorkspace = createIsolatedWorkspace;
+exports.removeIsolatedWorkspace = removeIsolatedWorkspace;
 exports.isLocalCheckout = isLocalCheckout;
+exports.gitAuthEnv = gitAuthEnv;
 exports.localCheckout = localCheckout;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
 const logger_1 = require("../utils/logger");
 const expression_1 = require("./expression");
+const job_container_1 = require("./job-container");
+const container_runtime_1 = require("./container-runtime");
 /** Marks a `path:` copy made by localCheckout, so it may be replaced. */
 const CHECKOUT_MARKER = '.secureci-checkout';
 /**
@@ -64,10 +70,34 @@ function copyWorkingCopy(srcDir, dstDir, exclude) {
         fs.cpSync(src, dst, {
             recursive: true,
             verbatimSymlinks: true,
+            // Copy-on-write clones where the file system supports them.
+            mode: fs.constants.COPYFILE_FICLONE,
             filter: (file) => !fs.existsSync(path.join(file, CHECKOUT_MARKER))
         });
     }
 }
+/**
+ * A copy of the working copy (uncommitted changes and .git included) for
+ * one job, in `parentDir`, for --isolate-workspace. Remove it with
+ * removeIsolatedWorkspace.
+ */
+function createIsolatedWorkspace(workingCopy, parentDir) {
+    const dir = fs.mkdtempSync(path.join(parentDir, 'workspace-'));
+    copyWorkingCopy(workingCopy, dir, dir);
+    return dir;
+}
+/**
+ * Remove a job's isolated workspace. Best effort: files a container step
+ * created as another user may not be removable, which is only warned about.
+ */
+function removeIsolatedWorkspace(dir) {
+    try {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+    catch (error) {
+        logger_1.logger.warn(`Couldn't remove the job's workspace copy ${dir}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 /**
  * Whether a step is `actions/checkout` of the repository being run (no
  * `repository:` input, or the current one in any case), which is served
@@ -101,7 +131,135 @@ function escapesViaSymlink(workspace, dest) {
     const real = fs.realpathSync(existing);
     return real !== root && !real.startsWith(root + path.sep);
 }
-function localCheckout(step, ctx, runtime, startTime) {
+/** Run git in `cwd` on the host; undefined when it fails. */
+function gitOutput(cwd, args, env) {
+    try {
+        return (0, child_process_1.execFileSync)('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            ...(env ? { env: { ...process.env, ...env } } : {})
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Environment for a git fetch from `url`: never prompts, and sends
+ * `token` (as actions/checkout does) only to an https URL on the server's
+ * own host, scoped to that host by the config key. Passed through the
+ * environment, so it never shows in the process list.
+ */
+function gitAuthEnv(url, token, serverUrl) {
+    const env = { GIT_TERMINAL_PROMPT: '0' };
+    let target;
+    let server;
+    try {
+        target = new URL(url);
+        server = new URL(serverUrl);
+    }
+    catch {
+        return env;
+    }
+    if (!token || target.protocol !== 'https:' || target.host !== server.host) {
+        return env;
+    }
+    return {
+        ...env,
+        GIT_CONFIG_COUNT: '1',
+        GIT_CONFIG_KEY_0: `http.https://${target.host}/.extraheader`,
+        GIT_CONFIG_VALUE_0: `AUTHORIZATION: basic ${Buffer.from(`x-access-token:${token}`).toString('base64')}`
+    };
+}
+/** `fetch-depth`: a non-negative integer, default 1 as on GitHub; 0 is all. */
+function fetchDepth(raw) {
+    const n = Number(raw === undefined || raw === '' ? 1 : raw);
+    return Number.isInteger(n) && n >= 0 ? n : 1;
+}
+/**
+ * Check out `commit` (fetched from `source` when given, else from the
+ * local repository) into an empty `dest`, with `depth` commits of history
+ * (0: all). The working copy's `.git` is only read: a full-depth local
+ * checkout shares its objects; anything fetched lands in `dest` only.
+ * Returns the commit checked out, or undefined.
+ */
+function cloneInto(workspace, dest, what, depth) {
+    const ok = (args, cwd = dest, env) => gitOutput(cwd, args, env) !== undefined;
+    const depthArgs = depth > 0 ? ['--depth', String(depth)] : [];
+    if ('commit' in what && depth === 0) {
+        return ok(['clone', '--quiet', '--shared', '--no-checkout', '--', workspace, dest], workspace) && ok(['checkout', '--quiet', '--detach', what.commit])
+            ? what.commit
+            : undefined;
+    }
+    fs.mkdirSync(dest, { recursive: true });
+    if (!ok(['init', '--quiet']) || !ok(['remote', 'add', 'origin', workspace])) {
+        return undefined;
+    }
+    const [source, ref, env] = 'commit' in what
+        ? [`file://${workspace}`, what.commit, undefined]
+        : [what.source, what.ref, what.env];
+    // `source` (the origin URL) and `ref` come from outside: never let either
+    // be read as an option (`--upload-pack=<cmd>`), and never allow the
+    // `ext::` transport, which runs a command, whatever the user's config says.
+    if (!ok([
+        '-c',
+        'protocol.ext.allow=never',
+        'fetch',
+        '--quiet',
+        '--no-tags',
+        ...depthArgs,
+        '--end-of-options',
+        source,
+        ref
+    ], dest, env)) {
+        return undefined;
+    }
+    const commit = gitOutput(dest, [
+        'rev-parse',
+        '--verify',
+        'FETCH_HEAD^{commit}'
+    ]);
+    return commit && ok(['checkout', '--quiet', '--detach', commit])
+        ? commit
+        : undefined;
+}
+/**
+ * The commit `ref` names in the local repository (as given, else as a
+ * branch of `origin`), or undefined. A ref that looks like an option is
+ * never passed to git.
+ */
+function resolveLocalRef(workspace, ref) {
+    if (ref.startsWith('-'))
+        return undefined;
+    for (const candidate of [ref, `refs/remotes/origin/${ref}`]) {
+        const sha = gitOutput(workspace, [
+            'rev-parse',
+            '--verify',
+            '--quiet',
+            '--end-of-options',
+            `${candidate}^{commit}`
+        ]);
+        if (sha)
+            return sha;
+    }
+    return undefined;
+}
+/**
+ * Submodules of the working copy that aren't initialized (`git submodule
+ * status` marks them with "-"), by path.
+ */
+function uninitializedSubmodules(workspace) {
+    if (!fs.existsSync(path.join(workspace, '.gitmodules')))
+        return [];
+    const status = gitOutput(workspace, ['submodule', 'status', '--recursive']);
+    return (status ?? '')
+        .split('\n')
+        .filter((line) => line.startsWith('-'))
+        .map((line) => line.slice(1).split(' ')[1])
+        .filter(Boolean);
+}
+function localCheckout(step, ctx, runtime, startTime, options = {}) {
     const withValues = (0, expression_1.substituteRecord)(step.with, ctx);
     const outputs = {
         ref: String(ctx.github.ref ?? ''),
@@ -111,12 +269,7 @@ function localCheckout(step, ctx, runtime, startTime) {
         logger_1.logger.error(error);
         return { step, success: false, error, duration: Date.now() - startTime };
     };
-    const ref = withValues.ref;
-    if (ref &&
-        ![ctx.github.ref, ctx.github.ref_name, ctx.github.sha].includes(ref)) {
-        logger_1.logger.warn(`actions/checkout: ignoring ref "${ref}"; using the local working copy (pass --no-local-checkout to run the real action)`);
-    }
-    const workspace = process.cwd();
+    const workspace = runtime.workspace;
     const dest = path.resolve(workspace, withValues.path || '.');
     const relative = path.relative(workspace, dest);
     if (relative.startsWith('..') ||
@@ -124,6 +277,37 @@ function localCheckout(step, ctx, runtime, startTime) {
         escapesViaSymlink(workspace, dest)) {
         return fail(`actions/checkout: path "${withValues.path}" is outside the workspace`);
     }
+    // A ref other than the current one: check out that commit, when the local
+    // repository has it, into path: (never over the user's working copy).
+    // With --fetch-refs, a ref the local repository lacks is fetched from
+    // origin into the path: copy (never into the user's repository).
+    const ref = withValues.ref;
+    let commit;
+    let fetchFrom;
+    if (ref &&
+        ![ctx.github.ref, ctx.github.ref_name, ctx.github.sha].includes(ref)) {
+        commit = resolveLocalRef(workspace, ref);
+        if (relative === '') {
+            logger_1.logger.warn(`actions/checkout: not checking out ref "${ref}" over your working copy; add a path: to check it out there, or pass --no-local-checkout to run the real action`);
+            commit = undefined;
+        }
+        else if (!commit && options.fetchRefs && !ref.startsWith('-')) {
+            fetchFrom = gitOutput(workspace, ['remote', 'get-url', 'origin']);
+            if (!fetchFrom) {
+                return fail(`actions/checkout: can't fetch ref "${ref}": the local repository has no origin remote`);
+            }
+        }
+        else if (!commit) {
+            logger_1.logger.warn(`actions/checkout: ref "${ref}" isn't in the local repository; using the local working copy (pass --fetch-refs to fetch it from origin, or --no-local-checkout to run the real action)`);
+        }
+    }
+    const submodules = String(withValues.submodules ?? '').toLowerCase();
+    if (submodules === 'true' || submodules === 'recursive') {
+        const missing = uninitializedSubmodules(workspace);
+        if (missing.length > 0) {
+            logger_1.logger.warn(`actions/checkout: submodules aren't initialized in your working copy (${missing.join(', ')}); run \`git submodule update --init --recursive\` first`);
+        }
+    }
     let output = 'Using local working copy';
     if (relative !== '') {
         if (fs.existsSync(dest)) {
@@ -134,14 +318,46 @@ function localCheckout(step, ctx, runtime, startTime) {
                 return fail(`actions/checkout: path "${withValues.path}" already exists in the working copy; remove it or pass --no-local-checkout`);
             }
         }
-        copyWorkingCopy(workspace, dest, dest);
+        const depth = fetchDepth(withValues['fetch-depth']);
+        if (fetchFrom) {
+            const token = withValues.token || String(ctx.github.token ?? '');
+            const fetched = cloneInto(workspace, dest, {
+                ref: String(ref),
+                source: fetchFrom,
+                env: gitAuthEnv(fetchFrom, token, String(ctx.github.server_url ?? 'https://github.com'))
+            }, depth);
+            if (!fetched) {
+                fs.rmSync(dest, { recursive: true, force: true });
+                return fail(`actions/checkout: couldn't fetch ref "${ref}" from origin (${fetchFrom})`);
+            }
+            outputs.ref = String(ref);
+            outputs.commit = fetched;
+            output = `Fetched ${ref} (${fetched.slice(0, 7)}) to ${relative}`;
+        }
+        else if (commit) {
+            // A local clone (sharing the repository's objects at full depth):
+            // nothing is fetched and the working copy's .git is only read.
+            if (!cloneInto(workspace, dest, { commit }, depth)) {
+                fs.rmSync(dest, { recursive: true, force: true });
+                return fail(`actions/checkout: couldn't check out ref "${ref}" to "${withValues.path}"`);
+            }
+            outputs.ref = String(ref);
+            outputs.commit = commit;
+            output = `Checked out ${ref} (${commit.slice(0, 7)}) to ${relative}`;
+        }
+        else {
+            copyWorkingCopy(workspace, dest, dest);
+            output = `Using local working copy (copied to ${relative})`;
+        }
         fs.writeFileSync(path.join(dest, CHECKOUT_MARKER), '');
-        output = `Using local working copy (copied to ${relative})`;
         const postStep = { name: `Post ${step.name || step.uses}` };
         runtime.postSteps.push({
             step: postStep,
             condition: 'always()',
             run: async () => {
+                // Files a container step created as root may not be removable by
+                // the host user: remove the copy from inside the container first.
+                await (0, job_container_1.removeInContainer)(runtime, path.posix.join(container_runtime_1.CONTAINER_WORKDIR, ...relative.split(path.sep)));
                 fs.rmSync(dest, { recursive: true, force: true });
                 return { step: postStep, success: true, duration: 0 };
             }