Update And Pin Remote Actions

Use this guide when a playbook references a remote action with uses: (for example github.com/acme/actions/signage@v1) and you need to fetch it into the local cache, understand what preflight.lock records for it, deliberately move it to a newer revision, and keep every controller that runs the playbook resolving the exact same commit.

Prerequisites

• A playbook task that already uses (or will use) a remote action ref in host/org/repo[/path/to/action]@revision form. See Remote Action Refs for the exact shape.
• Network access to the remote Git host for the first fetch of a given revision. Preflight fetches over plain HTTPS clone URLs; no git binary is required on the controller.
• A shell in your project root — the directory that holds preflight.yml and the playbook. preflight action fetch reads and writes preflight.lock relative to the current working directory, so run it from the same place you run apply/plan/validate.

1. Reference A Remote Action

Add the uses: reference to a task:

tasks:
  - name: Apply signage configuration
    uses: github.com/acme/actions/signage@v1
    with:
      display_name: lobby-01

The ref before @ is host/org/repo[/path/to/action]; the part after @ is a tag, branch, or commit SHA. See Why remote refs are pinned for why this shape exists and how it fits alongside stdlib and local actions.

2. Fetch And Pin It

Fetch the ref into the local cache and record it in preflight.lock:

preflight action fetch github.com/acme/actions/signage@v1

On success Preflight prints the resolved commit for each ref it fetched (a fetch recurses through any nested remote uses: the action itself declares, so you may see more than one line):

Fetched github.com/acme/actions/signage@v1 -> 0123456789abcdef0123456789abcdef01234567

That downloads the action (and any sibling files next to action.yml) into the user-wide cache at:

~/.preflight/actions/github.com/acme/actions/signage@0123456789abcdef0123456789abcdef01234567/

and adds an entry to preflight.lock in the project root, keyed by the literal ref you fetched:

{
  "actions": {
    "github.com/acme/actions/signage@v1": {
      "ref": "github.com/acme/actions/signage@v1",
      "sha": "0123456789abcdef0123456789abcdef01234567",
      "pinned": "github.com/acme/actions/signage@0123456789abcdef0123456789abcdef01234567"
    }
  }
}

3. Inspect What Resolved

Confirm the resolved action’s identity, inputs, and tasks:

preflight action info github.com/acme/actions/signage@v1

This prints the action’s name, version, description, author, its input definitions (with required/default markers), and the task names it expands to. It resolves through the same cache and lockfile as a playbook run, so it fails the same way a missing fetch would.

4. Update A Pinned Ref

Preflight has no action update subcommand and action fetch has no force flag. Once a ref is in preflight.lock, fetching that exact same ref string again reuses the pinned commit already recorded — it does not re-check the remote for a newer commit. There are two supported ways to move forward, depending on what “update” means for you:

Move to a new version. Change the ref in the playbook to a new tag or SHA (for example @v1 to @v2), then fetch it:

preflight action fetch github.com/acme/actions/signage@v2

Because the ref string is different, this adds a new entry to preflight.lock alongside the old one; it does not touch the @v1 entry.

Force re-resolution of the same ref (for example, a floating branch ref whose tip moved upstream). Remove that ref’s entry from the actions object in preflight.lock — delete the key by hand, or delete the whole file if it only contains that one entry — then fetch the same ref again:

preflight action fetch github.com/acme/actions/signage@main

With no lockfile entry to reuse, the fetch re-resolves the ref against the remote and writes a fresh pinned entry.

5. Commit The Lockfile

Commit preflight.lock alongside the playbook change:

git add preflight.lock
git commit -m "Pin signage action to v2"

Every controller that checks out this commit and runs apply/check/ stage resolves the same pinned commit from its own local cache (or fetches it once, identically, if its cache doesn’t have it yet). Without a committed lockfile, two controllers fetching a floating ref like @main at different times could pin to different commits.

Troubleshooting

Related Docs

• Execution model — why the lockfile and resolver order work the way they do
• Write an action
• Stage bundles for air-gapped deployment
• Playbook and action YAML reference