actions-up 1.13.0 → 1.14.1

package/dist/core/scan-github-actions.js

@@ -1,156 +1,156 @@
-import { ACTIONS_DIRECTORY, GITHUB_DIRECTORY, WORKFLOWS_DIRECTORY } from "./constants.js";
-import { isYamlFile } from "./fs/is-yaml-file.js";
-import { scanWorkflowFile } from "./scan-workflow-file.js";
-import { scanActionFile } from "./scan-action-file.js";
-import { isAbsolute, join, relative, resolve } from "node:path";
-import { readFile, readdir, stat } from "node:fs/promises";
-async function scanGitHubActions(p = process.cwd(), m = GITHUB_DIRECTORY) {
+import { ACTIONS_DIRECTORY as e, GITHUB_DIRECTORY as t, WORKFLOWS_DIRECTORY as n } from "./constants.js";
+import { isYamlFile as r } from "./fs/is-yaml-file.js";
+import { scanWorkflowFile as i } from "./scan-workflow-file.js";
+import { scanActionFile as a } from "./scan-action-file.js";
+import { isAbsolute as o, join as s, relative as c, resolve as l } from "node:path";
+import { readFile as u, readdir as d, stat as f } from "node:fs/promises";
+async function p(u = process.cwd(), p = t) {
 	let h = {
 		compositeActions: /* @__PURE__ */ new Map(),
 		workflows: /* @__PURE__ */ new Map(),
 		actions: []
-	}, g = resolve(p);
-	function _(e, a) {
-		let o = relative(e, a);
-		return o !== "" && !o.startsWith("..") && !isAbsolute(o);
+	}, g = l(u);
+	function _(e, t) {
+		let n = c(e, t);
+		return n !== "" && !n.startsWith("..") && !o(n);
 	}
-	let v = join(g, m);
+	let v = s(g, p);
 	function y(e) {
 		return e.includes("..") || e.includes("/") || e.includes("\\") ? (console.warn(`Skipping invalid name: ${e}`), !1) : !0;
 	}
 	async function b(e) {
 		try {
-			let a = await stat(e);
-			return typeof a.isFile == "function" ? a.isFile() : !1;
+			let t = await f(e);
+			return typeof t.isFile == "function" ? t.isFile() : !1;
 		} catch {
 			return !1;
 		}
 	}
-	let x = join(v, WORKFLOWS_DIRECTORY);
+	let x = s(v, n);
 	try {
-		if ((await stat(x)).isDirectory()) {
-			let e = (await readdir(x)).filter((e) => y(e) ? isYamlFile(e) : !1).map(async (e) => {
-				let a = join(x, e);
+		if ((await f(x)).isDirectory()) {
+			let e = (await d(x)).filter((e) => y(e) ? r(e) : !1).map(async (e) => {
+				let t = s(x, e);
 				try {
-					let s = await scanWorkflowFile(a);
+					let r = await i(t);
 					return {
-						path: `${m}/${WORKFLOWS_DIRECTORY}/${e}`,
+						path: `${p}/${n}/${e}`,
 						success: !0,
-						actions: s
+						actions: r
 					};
 				} catch {
 					return {
-						path: `${m}/${WORKFLOWS_DIRECTORY}/${e}`,
+						path: `${p}/${n}/${e}`,
 						success: !1,
 						actions: []
 					};
 				}
-			}), a = await Promise.all(e);
-			for (let e of a) e.success && e.path && (e.actions.length > 0 ? (h.workflows.set(e.path, e.actions), h.actions.push(...e.actions)) : h.workflows.set(e.path, []));
+			}), t = await Promise.all(e);
+			for (let e of t) e.success && e.path && (e.actions.length > 0 ? (h.workflows.set(e.path, e.actions), h.actions.push(...e.actions)) : h.workflows.set(e.path, []));
 		}
 	} catch {}
 	try {
-		let e = join(g, "action.yml"), a = join(g, "action.yaml"), o = null, s = [];
+		let e = s(g, "action.yml"), t = s(g, "action.yaml"), n = null, r = [];
 		if (await b(e)) try {
-			s = await scanActionFile(e), o = e;
+			r = await a(e), n = e;
 		} catch {
-			o = null;
+			n = null;
 		}
-		if (!o && await b(a)) try {
-			s = await scanActionFile(a), o = a;
+		if (!n && await b(t)) try {
+			r = await a(t), n = t;
 		} catch {
-			o = null;
+			n = null;
 		}
-		if (o) {
-			let e = relative(g, o);
-			h.compositeActions.set(e, e), s.length > 0 && h.actions.push(...s);
+		if (n) {
+			let e = c(g, n);
+			h.compositeActions.set(e, e), r.length > 0 && h.actions.push(...r);
 		}
 	} catch {}
-	let S = join(v, ACTIONS_DIRECTORY);
+	let S = s(v, e);
 	try {
-		if ((await stat(S)).isDirectory()) {
-			let a = (await readdir(S)).map(async (a) => {
-				if (!y(a)) return null;
-				let o = join(S, a);
+		if ((await f(S)).isDirectory()) {
+			let t = (await d(S)).map(async (t) => {
+				if (!y(t)) return null;
+				let n = s(S, t);
 				try {
-					if (!(await stat(o)).isDirectory()) return null;
-					let s = join(o, "action.yml"), c = [];
+					if (!(await f(n)).isDirectory()) return null;
+					let r = s(n, "action.yml"), i = [];
 					try {
-						c = await scanActionFile(s);
+						i = await a(r);
 					} catch {
 						try {
-							s = join(o, "action.yaml"), c = await scanActionFile(s);
+							r = s(n, "action.yaml"), i = await a(r);
 						} catch {
 							return null;
 						}
 					}
 					return {
-						path: `${m}/${ACTIONS_DIRECTORY}/${a}`,
-						name: a,
-						actions: c
+						path: `${p}/${e}/${t}`,
+						name: t,
+						actions: i
 					};
 				} catch {
 					return null;
 				}
-			}), o = await Promise.all(a);
-			for (let e of o) e && (h.compositeActions.set(e.name, e.path), h.actions.push(...e.actions));
+			}), n = await Promise.all(t);
+			for (let e of n) e && (h.compositeActions.set(e.name, e.path), h.actions.push(...e.actions));
 		}
 	} catch {}
 	try {
-		let e = await getCurrentRepoSlug(g);
+		let e = await m(g);
 		if (e) {
 			if (process.env.ACTIONS_UP_TEST_THROW === "1") throw Error("test");
-			let a = /* @__PURE__ */ new Set(), o = [];
-			for (let s of h.actions) {
-				if (s.type !== "external") continue;
-				let c = s.name.split("/");
-				if (c.length < 3 || `${c[0]}/${c[1]}` !== e) continue;
-				let l = join(g, ...c.slice(2));
-				_(g, l) && (a.has(l) || (a.add(l), o.push(l)));
+			let t = /* @__PURE__ */ new Set(), n = [];
+			for (let r of h.actions) {
+				if (r.type !== "external") continue;
+				let i = r.name.split("/");
+				if (i.length < 3 || `${i[0]}/${i[1]}` !== e) continue;
+				let a = s(g, ...i.slice(2));
+				_(g, a) && (t.has(a) || (t.add(a), n.push(a)));
 			}
-			async function s() {
-				if (o.length === 0) return;
-				let c = o.splice(0), u = await Promise.all(c.map(async (o) => {
+			async function r() {
+				if (n.length === 0) return;
+				let i = n.splice(0), o = await Promise.all(i.map(async (n) => {
 					try {
-						let s = join(o, "action.yml"), c = join(o, "action.yaml"), u = s;
+						let r = s(n, "action.yml"), i = s(n, "action.yaml"), o = r;
 						try {
-							if (!(await stat(s)).isFile()) throw Error("not a file");
+							if (!(await f(r)).isFile()) throw Error("not a file");
 						} catch {
-							if (!(await stat(c)).isFile()) throw Error("not a file");
-							u = c;
+							if (!(await f(i)).isFile()) throw Error("not a file");
+							o = i;
 						}
-						let d = await scanActionFile(u);
-						d.length > 0 && h.actions.push(...d);
-						let f = [];
-						for (let o of d) {
-							if (o.type !== "external") continue;
-							let s = o.name.split("/");
-							if (s.length < 3 || `${s[0]}/${s[1]}` !== e) continue;
-							let c = join(g, ...s.slice(2));
-							_(g, c) && (a.has(c) || (a.add(c), f.push(c)));
+						let c = await a(o);
+						c.length > 0 && h.actions.push(...c);
+						let l = [];
+						for (let n of c) {
+							if (n.type !== "external") continue;
+							let r = n.name.split("/");
+							if (r.length < 3 || `${r[0]}/${r[1]}` !== e) continue;
+							let i = s(g, ...r.slice(2));
+							_(g, i) && (t.has(i) || (t.add(i), l.push(i)));
 						}
-						return f;
+						return l;
 					} catch {
 						return [];
 					}
 				}));
-				for (let e of u) for (let a of e) o.push(a);
-				await s();
+				for (let e of o) for (let t of e) n.push(t);
+				await r();
 			}
-			await s();
+			await r();
 		}
 	} catch {}
 	return h;
 }
-async function getCurrentRepoSlug(e) {
-	let a = process.env.GITHUB_REPOSITORY;
-	if (a && /^[^\s/]+\/[^\s/]+$/u.test(a)) return a;
+async function m(e) {
+	let t = process.env.GITHUB_REPOSITORY;
+	if (t && /^[^\s/]+\/[^\s/]+$/u.test(t)) return t;
 	try {
-		let a = await readFile(join(e, ".git", "config"), "utf8"), o = a.match(/\[remote "origin"\][\s\S]*?url\s*=\s*(?<url>.+)/u)?.groups?.url?.trim();
-		if (o ||= a.match(/url\s*=\s*(?<url>.+)/u)?.groups?.url?.trim(), !o) return null;
-		let s = o.match(/github\.com[/:](?<owner>[^/]+)\/(?<repo>[^./]+)(?:\.git)?$/u);
-		if (s?.groups) return `${s.groups.owner}/${s.groups.repo}`;
+		let t = await u(s(e, ".git", "config"), "utf8"), n = t.match(/\[remote "origin"\][\s\S]*?url\s*=\s*(?<url>.+)/u)?.groups?.url?.trim();
+		if (n ||= t.match(/url\s*=\s*(?<url>.+)/u)?.groups?.url?.trim(), !n) return null;
+		let r = n.match(/github\.com[/:](?<owner>[^/]+)\/(?<repo>[^./]+)(?:\.git)?$/u);
+		if (r?.groups) return `${r.groups.owner}/${r.groups.repo}`;
 	} catch {}
 	return null;
 }
-export { scanGitHubActions };
+export { p as scanGitHubActions };

package/dist/core/scan-recursive.js

@@ -1,46 +1,46 @@
-import { isCompositeActionStructure } from "./schema/composite/is-composite-action-structure.js";
-import { scanCompositeActionAst } from "./ast/scanners/scan-composite-action-ast.js";
-import { isWorkflowStructure } from "./schema/workflow/is-workflow-structure.js";
-import { findYamlFilesRecursive } from "./fs/find-yaml-files-recursive.js";
-import { scanWorkflowAst } from "./ast/scanners/scan-workflow-ast.js";
-import { readYamlDocument } from "./fs/read-yaml-document.js";
-import { dirname, relative, resolve } from "node:path";
-async function scanRecursive(u, d) {
+import { isCompositeActionStructure as e } from "./schema/composite/is-composite-action-structure.js";
+import { scanCompositeActionAst as t } from "./ast/scanners/scan-composite-action-ast.js";
+import { isWorkflowStructure as n } from "./schema/workflow/is-workflow-structure.js";
+import { findYamlFilesRecursive as r } from "./fs/find-yaml-files-recursive.js";
+import { scanWorkflowAst as i } from "./ast/scanners/scan-workflow-ast.js";
+import { readYamlDocument as a } from "./fs/read-yaml-document.js";
+import { dirname as o, relative as s, resolve as c } from "node:path";
+async function l(l, d) {
 	let f = {
 		compositeActions: /* @__PURE__ */ new Map(),
 		workflows: /* @__PURE__ */ new Map(),
 		actions: []
-	}, p = resolve(u), m = resolve(p, d), h;
+	}, p = c(l), m = c(p, d), h;
 	try {
-		h = await findYamlFilesRecursive(m);
+		h = await r(m);
 	} catch {
 		return f;
 	}
-	let g = h.map(async (o) => {
-		let s = relative(p, o);
+	let g = h.map(async (r) => {
+		let o = s(p, r);
 		try {
-			let { document: c, content: l } = await readYamlDocument(o), u = c.toJSON();
-			if (isWorkflowStructure(u) && hasKey(u, "jobs")) return {
+			let { document: s, content: c } = await a(r), l = s.toJSON();
+			if (n(l) && u(l, "jobs")) return {
 				type: "workflow",
-				path: s,
-				actions: scanWorkflowAst(c, l, o)
+				path: o,
+				actions: i(s, c, r)
 			};
-			if (isCompositeActionStructure(u) && hasKey(u, "runs")) return {
+			if (e(l) && u(l, "runs")) return {
 				type: "action",
-				path: s,
-				actions: scanCompositeActionAst(c, l, o)
+				path: o,
+				actions: t(s, c, r)
 			};
 		} catch {}
 		return null;
 	}), _ = await Promise.all(g);
 	for (let e of _) if (e) if (e.type === "workflow") f.workflows.set(e.path, e.actions), f.actions.push(...e.actions);
 	else {
-		let i = dirname(e.path), a = i === "." || i === "" ? e.path : i;
-		f.compositeActions.set(a, e.path), f.actions.push(...e.actions);
+		let t = o(e.path), n = t === "." || t === "" ? e.path : t;
+		f.compositeActions.set(n, e.path), f.actions.push(...e.actions);
 	}
 	return f;
 }
-function hasKey(e, i) {
-	return typeof e == "object" && !!e && i in e;
+function u(e, t) {
+	return typeof e == "object" && !!e && t in e;
 }
-export { scanRecursive };
+export { l as scanRecursive };

package/dist/core/scan-workflow-file.js

@@ -1,7 +1,7 @@
-import { scanWorkflowAst } from "./ast/scanners/scan-workflow-ast.js";
-import { readYamlDocument } from "./fs/read-yaml-document.js";
-async function scanWorkflowFile(n) {
-	let { document: r, content: i } = await readYamlDocument(n);
-	return scanWorkflowAst(r, i, n);
+import { scanWorkflowAst as e } from "./ast/scanners/scan-workflow-ast.js";
+import { readYamlDocument as t } from "./fs/read-yaml-document.js";
+async function n(n) {
+	let { document: r, content: i } = await t(n);
+	return e(r, i, n);
 }
-export { scanWorkflowFile };
+export { n as scanWorkflowFile };

package/dist/core/schema/composite/is-composite-action-runs.js

@@ -1,4 +1,4 @@
-function isCompositeActionRuns(e) {
+function e(e) {
 	return typeof e != "object" || !e || Array.isArray(e) ? !1 : "using" in e;
 }
-export { isCompositeActionRuns };
+export { e as isCompositeActionRuns };

package/dist/core/schema/composite/is-composite-action-structure.js

@@ -1,6 +1,6 @@
-function isCompositeActionStructure(e) {
+function e(e) {
 	if (typeof e != "object" || !e || Array.isArray(e)) return !1;
 	let t = e;
 	return "name" in t || "description" in t || "runs" in t;
 }
-export { isCompositeActionStructure };
+export { e as isCompositeActionStructure };

package/dist/core/schema/workflow/is-workflow-structure.js

@@ -1,6 +1,6 @@
-function isWorkflowStructure(e) {
+function e(e) {
 	if (typeof e != "object" || !e || Array.isArray(e)) return !1;
 	let t = e;
 	return "on" in t || "name" in t || "jobs" in t;
 }
-export { isWorkflowStructure };
+export { e as isWorkflowStructure };

package/dist/core/updates/resolve-target-reference.d.ts

@@ -0,0 +1,10 @@
+import { ActionUpdate } from '../../types/action-update';
+import { UpdateStyle } from '../../types/update-style';
+/**
+ * Resolve the final reference that should be written back to the workflow.
+ *
+ * @param update - Update entry enriched with lookup data.
+ * @param style - Effective update style.
+ * @returns Update entry with resolved target reference fields.
+ */
+export declare function resolveTargetReference(update: ActionUpdate, style: UpdateStyle): ActionUpdate;

package/dist/core/updates/resolve-target-reference.js

@@ -0,0 +1,24 @@
+function e(e, t) {
+	return e.hasUpdate ? t === "sha" || e.currentRefType === "sha" ? e.latestSha ? {
+		...e,
+		targetRef: e.latestSha,
+		targetRefStyle: "sha"
+	} : {
+		...e,
+		targetRefStyle: null,
+		targetRef: null
+	} : e.currentRefType === "tag" && e.latestVersion ? {
+		...e,
+		targetRef: e.latestVersion,
+		targetRefStyle: "tag"
+	} : {
+		...e,
+		targetRefStyle: null,
+		targetRef: null
+	} : {
+		...e,
+		targetRefStyle: null,
+		targetRef: null
+	};
+}
+export { e as resolveTargetReference };

package/dist/core/versions/find-compatible-tag.js

@@ -1,27 +1,27 @@
-import { normalizeVersion } from "./normalize-version.js";
-import { isSemverLike } from "./is-semver-like.js";
-import semver from "semver";
-function findCompatibleTag(r, a, o) {
-	if (!a || !isSemverLike(a) || r.length === 0) return null;
-	let s = semver.valid(normalizeVersion(a));
+import { normalizeVersion as e } from "./normalize-version.js";
+import { isSemverLike as t } from "./is-semver-like.js";
+import n from "semver";
+function r(r, a, o) {
+	if (!a || !t(a) || r.length === 0) return null;
+	let s = n.valid(e(a));
 	if (!s) return null;
-	let c = semver.major(s), l = semver.minor(s), u = [];
+	let c = n.major(s), l = n.minor(s), u = [];
 	for (let i of r) {
-		if (!isSemverLike(i.tag)) continue;
-		let r = semver.valid(normalizeVersion(i.tag));
-		r && semver.gt(r, s) && semver.major(r) === c && (o === "patch" && semver.minor(r) !== l || u.push({
+		if (!t(i.tag)) continue;
+		let r = n.valid(e(i.tag));
+		r && n.gt(r, s) && n.major(r) === c && (o === "patch" && n.minor(r) !== l || u.push({
 			tag: i,
 			parsed: r
 		}));
 	}
-	return u.length === 0 ? null : (u.sort((e, n) => {
-		let r = semver.rcompare(e.parsed, n.parsed);
+	return u.length === 0 ? null : (u.sort((e, t) => {
+		let r = n.rcompare(e.parsed, t.parsed);
 		if (r !== 0) return r;
-		let a = getSemverSpecificity(e.tag.tag);
-		return getSemverSpecificity(n.tag.tag) - a;
+		let a = i(e.tag.tag);
+		return i(t.tag.tag) - a;
 	}), u[0].tag);
 }
-function getSemverSpecificity(e) {
+function i(e) {
 	return e.replace(/^v/u, "").split(".").length;
 }
-export { findCompatibleTag };
+export { r as findCompatibleTag };

package/dist/core/versions/get-update-level.js

@@ -1,10 +1,10 @@
-import semver from "semver";
-function getUpdateLevel(t, r) {
+import e from "semver";
+function t(t, r) {
 	if (!t || !r) return "unknown";
-	let i = normalizeVersion(t), a = normalizeVersion(r);
+	let i = n(t), a = n(r);
 	if (!i || !a) return "unknown";
-	if (semver.eq(i, a)) return "none";
-	let o = semver.diff(i, a);
+	if (e.eq(i, a)) return "none";
+	let o = e.diff(i, a);
 	if (!o) return "none";
 	switch (o) {
 		case "premajor":
@@ -16,8 +16,8 @@ function getUpdateLevel(t, r) {
 		default: return "unknown";
 	}
 }
-function normalizeVersion(t) {
-	let n = semver.coerce(t);
+function n(t) {
+	let n = e.coerce(t);
 	return n ? n.version : null;
 }
-export { getUpdateLevel };
+export { t as getUpdateLevel };

package/dist/core/versions/is-semver-like.js

@@ -1,4 +1,4 @@
-function isSemverLike(e) {
+function e(e) {
 	return typeof e == "string" && /^v?\d+(?:\.\d+){0,2}$/u.test(e.trim());
 }
-export { isSemverLike };
+export { e as isSemverLike };

package/dist/core/versions/is-sha.js

@@ -1,6 +1,6 @@
-function isSha(e) {
+function e(e) {
 	if (!e) return !1;
 	let t = e.replace(/^v/u, "");
 	return /^[0-9a-f]{7,40}$/iu.test(t);
 }
-export { isSha };
+export { e as isSha };

package/dist/core/versions/normalize-version.js

@@ -1,9 +1,9 @@
-import semver from "semver";
-function normalizeVersion(t) {
+import e from "semver";
+function t(t) {
 	if (!t) return null;
 	let n = t.replace(/^v/u, "");
 	if (/^[0-9a-f]{7,40}$/iu.test(n)) return t;
-	let r = semver.coerce(n);
+	let r = e.coerce(n);
 	return r ? r.version : t;
 }
-export { normalizeVersion };
+export { t as normalizeVersion };

package/dist/core/versions/read-inline-version-comment.js

@@ -1,9 +1,9 @@
-import { readFile } from "node:fs/promises";
-async function readInlineVersionComment(t, n, r) {
+import { readFile as e } from "node:fs/promises";
+async function t(t, n, r) {
 	try {
 		if (!t || !n || n <= 0) return null;
 		let i = r?.get(t);
-		i === void 0 && (i = await readFile(t, "utf8"), r && r.set(t, i));
+		i === void 0 && (i = await e(t, "utf8"), r && r.set(t, i));
 		let a = i.split("\n"), o = n - 1;
 		if (o < 0 || o >= a.length) return null;
 		let s = a[o].match(/#\s*(?<version>[Vv]?\d+(?:\.\d+){0,2}(?:[+-][\w\-.]+)?)/u);
@@ -11,4 +11,4 @@ async function readInlineVersionComment(t, n, r) {
 	} catch {}
 	return null;
 }
-export { readInlineVersionComment };
+export { t as readInlineVersionComment };

package/dist/package.js

@@ -1,2 +1,2 @@
-const version = "1.13.0";
-export { version };
+var e = "1.14.1";
+export { e as version };

package/dist/types/action-update.d.ts

@@ -6,7 +6,17 @@ export interface ActionUpdate {
   /**
    * Reason for skipping the update check.
    */
-  skipReason?: 'unknown' | 'branch'
+  skipReason?: 'unsupported-style' | 'unknown' | 'branch'
+
+  /**
+   * Detected style of the current reference in the source file.
+   */
+  currentRefType?: 'unknown' | 'branch' | 'sha' | 'tag'
+
+  /**
+   * Style of the final reference that should be written back to the file.
+   */
+  targetRefStyle?: 'sha' | 'tag' | null
 
   /**
    * Current version string.
@@ -23,6 +33,11 @@ export interface ActionUpdate {
    */
   status?: 'skipped' | 'ok'
 
+  /**
+   * Final reference that should be written back to the file.
+   */
+  targetRef?: string | null
+
   /**
    * SHA hash of the latest version.
    */

package/dist/types/update-style.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Strategy used when writing updated action references back to workflow files.
+ */
+export type UpdateStyle = 'preserve' | 'sha'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actions-up",
-  "version": "1.13.0",
-  "description": "Interactive CLI tool to update GitHub Actions to latest versions with SHA pinning",
+  "version": "1.14.1",
+  "description": "Interactive CLI tool to update GitHub Actions with SHA pinning or preserved refs",
   "keywords": [
     "github-actions",
     "actions",

package/readme.md

@@ -16,7 +16,7 @@ Actions Up scans your workflows and composite actions to discover every
 referenced GitHub Action, then checks for newer releases.
 
 Interactively upgrade and pin actions to exact commit SHAs for secure,
-reproducible CI and low-friction maintenance.
+reproducible CI, or preserve tag-style references when you need to stay on tags.
 
 ## Features
 
@@ -25,8 +25,8 @@ reproducible CI and low-friction maintenance.
   `action.yml`/`action.yaml`)
 - **Reusable Workflows**: Detects and updates reusable workflow calls at the job
   level
-- **SHA pinning**: Updates actions to use commit SHA instead of tags for better
-  security
+- **Flexible update styles**: Use SHA pinning by default, or preserve tag-style
+  references with `--style preserve`
 - **Batch Updates**: Update multiple actions at once
 - **Interactive Selection**: Choose which actions to update
 - **Breaking Changes Detection**: Warns about major version updates
@@ -124,7 +124,7 @@ This will:
    plus root `action.yml`/`action.yaml`
 2. Check for available updates
 3. Show an interactive list to select updates
-4. Apply selected updates with SHA pinning
+4. Apply selected updates with SHA pinning by default
 
 ### Auto-Update Mode
 
@@ -200,6 +200,24 @@ In `minor` and `patch` modes, Actions Up tries to find the newest compatible tag
 first (for example, from `@v4` in `minor` mode it will choose the latest
 `v4.x.y`). If no compatible version exists, that action is skipped.
 
+### Update Style
+
+By default, Actions Up writes updates as pinned SHAs:
+
+```bash
+npx actions-up --style sha
+```
+
+Use `--style preserve` to keep the current reference style:
+
+```bash
+npx actions-up --style preserve
+```
+
+`preserve` keeps tag references on tags and SHA references on SHAs. For example,
+`actions/checkout@v5` updates to `actions/checkout@v6.0.2`, while a SHA-pinned
+action continues updating to the latest resolved SHA.
+
 ## GitHub Actions Integration
 
 ### Automated PR Checks
@@ -500,7 +518,8 @@ Ignore comments (file/block/next-line/inline):
 Interactive CLI for developers who want control over GitHub Actions updates.
 
 - **vs. Dependabot/Renovate:** Dependabot and Renovate update via pull requests;
-  Actions Up is an interactive CLI with explicit SHA pinning.
+  Actions Up is an interactive CLI with explicit SHA pinning by default and an
+  opt-in preserve mode for tag users.
 - **vs. pinact:** pinact is a CLI to pin and update Actions and reusable
   workflows; Actions Up adds interactive selection and major update warnings.
 - **Zero-config:** `npx actions-up` runs immediately.