Skip to content

[docs] docs: update --image-tag CLI reference for digest-aware format #2095

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lpcox merged 1 commit into from
Apr 19, 2026
+13 −3
Merged

[docs] docs: update --image-tag CLI reference for digest-aware format #2095

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 13 additions & 3 deletions docs-site/src/content/docs/reference/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ awf [options] -- <command>
| `--work-dir <dir>` | string | `/tmp/awf-<timestamp>` | Working directory for temporary files |
| `--build-local` | flag | `false` | Build containers locally instead of pulling from registry |
| `--image-registry <url>` | string | `ghcr.io/github/gh-aw-firewall` | Container image registry |
| `--image-tag <tag>` | string | `latest` | Container image tag |
| `--image-tag <tag>` | string | `latest` | Container image tag. Supports optional per-image digest pinning: `<tag>,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...` |
| `--skip-pull` | flag | `false` | Use local images without pulling from registry |
| `-e, --env <KEY=VALUE>` | string | `[]` | Environment variable (repeatable) |
| `--env-all` | flag | `false` | Pass all host environment variables |
Expand Down Expand Up @@ -333,7 +333,17 @@ Custom container image registry URL.

### `--image-tag <tag>`

Container image tag to use.
Container image tag to use. Supports an optional digest-aware format for cryptographic image pinning:

```
<tag>,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...
```

Digest keys correspond to each runtime container image. When a digest is provided, the image reference is pinned to `<registry>/<image>:<tag>@<digest>`, preventing tag mutation attacks. The setup action's `image-tag` output produces this format automatically when `pull-images: true` is set.

Which agent image key is used depends on the `--agent-image` preset:
- `default` → `agent`
- `act` → `agent-act`

### `--skip-pull`

Expand Down Expand Up @@ -950,7 +960,7 @@ awf predownload [options]
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--image-registry <registry>` | string | `ghcr.io/github/gh-aw-firewall` | Container image registry |
| `--image-tag <tag>` | string | `latest` | Container image tag (applies to squid, agent, and api-proxy images) |
| `--image-tag <tag>` | string | `latest` | Container image tag (applies to squid, agent, agent-act, api-proxy, and cli-proxy images). Supports optional digest metadata — see [`--image-tag`](#--image-tag-tag) for format details. |
| `--agent-image <value>` | string | `default` | Agent image preset (`default`, `act`) or custom image |
| `--enable-api-proxy` | flag | `false` | Also download the API proxy image |

Expand Down
Loading