# Versions and pinning

> What the action reference in your workflow pins, and how to pin it to a commit SHA.

Your workflow references the action with a `uses:` ref, almost always the moving major tag `pullfrog/pullfrog@v0`. That ref pins less than it appears to.

## How the action is versioned

The published action is a thin bootstrap. The code behind both of its steps, the agent and the post-run cleanup that saves rotated credentials, comes from npm at `^<version>`, so a run's behavior tracks the latest release in the current version line.

The `uses:` ref fixes two things:

- The input and output contract, read from the action's `action.yml`.
- The npm range the bootstrap resolves: `^<version>` as of the pinned revision.

The `pullfrog/pullfrog@v0` tag tracks the latest `v0.x` release. The console writes this ref, and it is the recommended one.

## Pinning to a commit SHA

GitHub's [security hardening guide](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions) recommends pinning third-party actions to a full commit SHA, because tags can move. Dependabot, [StepSecurity](https://www.stepsecurity.io/) and `pin-github-action` do this for you and keep the version as a comment:

`.github/workflows/pullfrog.yml`:

```yaml
uses: pullfrog/pullfrog@abc123… # v0
```

A pinned SHA takes both steps from npm the same way the tag does, so the agent and the cleanup step still receive patch releases. Updating the pin is what picks up a new minor version. Dependabot bumps the SHA and the `# v0` comment together:

`.github/dependabot.yml`:

```yaml
version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly
```

## Freezing the code

A pinned SHA still installs the newest patch from npm. To run exactly the code at the pinned commit, set `PULLFROG_FORCE_LOCAL_CLI` in the step's `env:`:

`.github/workflows/pullfrog.yml`:

```yaml
- uses: pullfrog/pullfrog@abc123… # v0.1.137
  env:
    PULLFROG_FORCE_LOCAL_CLI: "1"
```

The run then uses that commit's source and the dependency versions its lockfile pins. A frozen workflow gets no fixes, security fixes included, until the pin moves, so keep Dependabot bumping the SHA and merge its updates promptly.

## Choosing a ref

| You want | Use |
|---|---|
| The simplest setup that stays current | `pullfrog/pullfrog@v0` |
| SHA pinning for a security policy | A commit SHA, with Dependabot to pick up new minor versions |
| Code that changes only when you move the pin | A commit SHA with `PULLFROG_FORCE_LOCAL_CLI: "1"` |

## OpenCode version

Runs on OpenCode are moving to OpenCode V2, and a run with no pin can use either version during the rollout. A repo stays on V1 when its checkout has code only V1 can load.

| Written for V1 | Runs on |
| --- | --- |
| A plugin or custom tool in `.opencode/plugin(s)` or `.opencode/tool(s)` | V1 only |
| A `plugin` list in `opencode.json` | V1 only |
| Agents, commands, skills, MCP servers and permissions | V2, as they are |

To choose a version yourself, set `PULLFROG_OPENCODE_VERSION` to `1` or `2` in the `env:` of your workflow:

`.github/workflows/pullfrog.yml`:

```yaml
env:
  PULLFROG_OPENCODE_VERSION: "1"
```

Each run logs its choice, for example `» opencode: V2 (default)`.
