From bd907077531fe11627347d597b5c132268c6eac2 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 5 Jan 2026 23:01:42 +0000
Subject: [PATCH 1/5] Initial plan


From e425a60fa377e2e8efa5406e36919315082b6681 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 5 Jan 2026 23:09:52 +0000
Subject: [PATCH 2/5] feat: add GitHub Action for installing awf

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
---
 README.md              |  57 +++++++++++++++++-
 action.yml             | 128 +++++++++++++++++++++++++++++++++++++++++
 docs/github_actions.md |  52 ++++++++++++-----
 docs/quickstart.md     |  23 +++++++-
 4 files changed, 244 insertions(+), 16 deletions(-)
 create mode 100644 action.yml

diff --git a/README.md b/README.md
index 7ba159480..3e74af02c 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,62 @@ sudo -E awf \
 
 For checksum verification, version pinning, and manual installation steps, see [Quick start](docs/quickstart.md).
 
-All published container images are cryptographically signed with cosign. See [docs/image-verification.md](docs/image-verification.md) for verification instructions.
+#### GitHub Action (recommended for CI/CD)
+
+Use the setup action in your workflows:
+
+```yaml
+steps:
+  - name: Setup awf
+    uses: githubnext/gh-aw-firewall@main
+    # with:
+    #   version: 'v1.0.0'  # Optional: defaults to latest
+
+  - name: Run command with firewall
+    run: sudo awf --allow-domains github.com -- curl https://api.github.com
+```
+
+#### Shell script
+
+```bash
+# Install latest version
+curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo bash
+
+# Install a specific version
+curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo bash -s -- v1.0.0
+
+# Or using environment variable
+curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo AWF_VERSION=v1.0.0 bash
+```
+
+The shell installer automatically:
+- Downloads the latest release binary (or a specified version)
+- Verifies SHA256 checksum to detect corruption or tampering
+- Validates the file is a valid Linux executable
+- Protects against 404 error pages being saved as binaries
+- Installs to `/usr/local/bin/awf`
+
+**Alternative: Manual installation**
+
+```bash
+# Download the latest release binary
+curl -fL https://github.com/githubnext/gh-aw-firewall/releases/latest/download/awf-linux-x64 -o awf
+
+# Download checksums for verification
+curl -fL https://github.com/githubnext/gh-aw-firewall/releases/latest/download/checksums.txt -o checksums.txt
+
+# Verify SHA256 checksum
+sha256sum -c checksums.txt --ignore-missing
+
+# Install
+chmod +x awf
+sudo mv awf /usr/local/bin/
+
+# Verify installation
+sudo awf --help
+```
+
+**Docker Image Verification:** All published container images are cryptographically signed with cosign. See [docs/image-verification.md](docs/image-verification.md) for verification instructions.
 
 ## Explore the docs
 
diff --git a/action.yml b/action.yml
new file mode 100644
index 000000000..92e3c816a
--- /dev/null
+++ b/action.yml
@@ -0,0 +1,128 @@
+name: 'Setup AWF'
+description: 'Install the Agentic Workflow Firewall (awf) CLI tool'
+author: 'GitHub'
+branding:
+  icon: 'shield'
+  color: 'blue'
+
+inputs:
+  version:
+    description: 'Version to install (e.g., v1.0.0). Defaults to latest release.'
+    required: false
+    default: 'latest'
+
+outputs:
+  version:
+    description: 'The version of awf that was installed'
+    value: ${{ steps.install.outputs.version }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Validate runner OS
+      shell: bash
+      run: |
+        if [ "$RUNNER_OS" != "Linux" ]; then
+          echo "::error::This action only supports Linux runners. Current OS: $RUNNER_OS"
+          exit 1
+        fi
+
+    - name: Install awf
+      id: install
+      shell: bash
+      env:
+        INPUT_VERSION: ${{ inputs.version }}
+      run: |
+        set -euo pipefail
+
+        REPO="githubnext/gh-aw-firewall"
+        BINARY_NAME="awf-linux-x64"
+        INSTALL_DIR="${RUNNER_TEMP}/awf-bin"
+
+        # Create install directory
+        mkdir -p "$INSTALL_DIR"
+
+        # Determine version
+        if [ "$INPUT_VERSION" = "latest" ] || [ -z "$INPUT_VERSION" ]; then
+          echo "Fetching latest release version..."
+          VERSION=$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest" | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
+          if [ -z "$VERSION" ]; then
+            echo "::error::Failed to fetch latest version from GitHub API"
+            exit 1
+          fi
+          echo "Latest version: $VERSION"
+        else
+          VERSION="$INPUT_VERSION"
+          # Validate version format
+          if ! echo "$VERSION" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "::error::Invalid version format: $VERSION. Expected format: v1.0.0"
+            exit 1
+          fi
+        fi
+
+        echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+        # Download URLs
+        BASE_URL="https://github.com/${REPO}/releases/download/${VERSION}"
+        BINARY_URL="${BASE_URL}/${BINARY_NAME}"
+        CHECKSUMS_URL="${BASE_URL}/checksums.txt"
+
+        # Download binary
+        echo "Downloading awf ${VERSION}..."
+        if ! curl -fsSL "$BINARY_URL" -o "$INSTALL_DIR/awf"; then
+          echo "::error::Failed to download binary from $BINARY_URL"
+          exit 1
+        fi
+
+        # Download checksums
+        echo "Downloading checksums..."
+        if ! curl -fsSL "$CHECKSUMS_URL" -o "$INSTALL_DIR/checksums.txt"; then
+          echo "::error::Failed to download checksums from $CHECKSUMS_URL"
+          exit 1
+        fi
+
+        # Verify checksum
+        echo "Verifying SHA256 checksum..."
+        EXPECTED_SUM=$(awk -v fname="$BINARY_NAME" '$2 == fname {print $1; exit}' "$INSTALL_DIR/checksums.txt")
+
+        if [ -z "$EXPECTED_SUM" ]; then
+          echo "::error::Could not find checksum for $BINARY_NAME in checksums.txt"
+          exit 1
+        fi
+
+        # Validate checksum format (64 hex characters)
+        if ! echo "$EXPECTED_SUM" | grep -qE '^[a-fA-F0-9]{64}$'; then
+          echo "::error::Invalid checksum format: $EXPECTED_SUM"
+          exit 1
+        fi
+
+        # Normalize to lowercase for comparison
+        EXPECTED_SUM=$(echo "$EXPECTED_SUM" | tr 'A-F' 'a-f')
+        ACTUAL_SUM=$(sha256sum "$INSTALL_DIR/awf" | awk '{print $1}' | tr 'A-F' 'a-f')
+
+        if [ "$EXPECTED_SUM" != "$ACTUAL_SUM" ]; then
+          echo "::error::Checksum verification failed!"
+          echo "Expected: $EXPECTED_SUM"
+          echo "Got:      $ACTUAL_SUM"
+          exit 1
+        fi
+
+        echo "Checksum verification passed ✓"
+
+        # Verify it's a valid ELF executable
+        if ! file "$INSTALL_DIR/awf" | grep -q "ELF.*executable"; then
+          echo "::error::Downloaded file is not a valid Linux executable"
+          exit 1
+        fi
+
+        # Make executable
+        chmod +x "$INSTALL_DIR/awf"
+
+        # Clean up checksums file
+        rm -f "$INSTALL_DIR/checksums.txt"
+
+        # Add to PATH
+        echo "$INSTALL_DIR" >> "$GITHUB_PATH"
+
+        echo "Successfully installed awf ${VERSION} to $INSTALL_DIR"
+        echo "awf is now available in PATH for subsequent steps"
diff --git a/docs/github_actions.md b/docs/github_actions.md
index 76b09868b..320ae7047 100644
--- a/docs/github_actions.md
+++ b/docs/github_actions.md
@@ -2,6 +2,39 @@
 
 ## Installation in GitHub Actions
 
+### Using the Setup Action (Recommended)
+
+The simplest way to install awf in GitHub Actions is using the setup action:
+
+```yaml
+steps:
+  - name: Setup awf
+    uses: githubnext/gh-aw-firewall@main
+    # with:
+    #   version: 'v1.0.0'  # Optional: defaults to latest
+
+  - name: Run command with firewall
+    run: sudo awf --allow-domains github.com -- curl https://api.github.com
+```
+
+The action:
+- Downloads the specified version (or latest) from GitHub releases
+- Verifies SHA256 checksum
+- Installs to PATH for subsequent steps
+
+### Using the Install Script
+
+Alternatively, use the install script:
+
+```yaml
+steps:
+  - name: Install awf
+    run: |
+      curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo bash
+```
+
+### Building from Source
+
 In GitHub Actions workflows, the runner already has root access:
 
 ```yaml
@@ -37,16 +70,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - name: Install Firewall
-        run: |
-          npm install
-          npm run build
-          npm link
+      - name: Setup awf
+        uses: githubnext/gh-aw-firewall@main
 
       - name: Install GitHub Copilot CLI
         run: npm install -g @github/copilot@latest
@@ -55,7 +80,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.COPILOT_CLI_TOKEN }}
         run: |
-          awf \
+          sudo awf \
             --allow-domains github.com,api.github.com,githubusercontent.com \
             'copilot --help'
 ```
@@ -114,9 +139,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install Firewall
-        run: |
-          curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo bash
+      - name: Setup awf
+        uses: githubnext/gh-aw-firewall@main
 
       - name: Test with Firewall
         env:
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 3693e76f1..da10b0d2a 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -10,9 +10,30 @@ Get started with the firewall in 5 minutes!
 
 ## Installation
 
+### Option 1: Install Script (Recommended for Local Use)
+
+```bash
+# Install latest version
+curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo bash
+
+# Verify installation
+sudo awf --version
+```
+
+### Option 2: GitHub Action (Recommended for CI/CD)
+
+```yaml
+- name: Setup awf
+  uses: githubnext/gh-aw-firewall@main
+```
+
+See [GitHub Actions Integration](github_actions.md) for more details.
+
+### Option 3: Build from Source
+
 ```bash
 # Clone the repository
-git clone <your-repo-url> awf
+git clone https://github.com/githubnext/gh-aw-firewall.git awf
 cd awf
 
 # Install dependencies

From f480e4220dc584f81ce20d75fead066ab13e65c3 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 5 Jan 2026 23:13:14 +0000
Subject: [PATCH 3/5] fix: address code review comments for action.yml

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
---
 action.yml | 35 +++++++++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 8 deletions(-)

diff --git a/action.yml b/action.yml
index 92e3c816a..30f4b001f 100644
--- a/action.yml
+++ b/action.yml
@@ -19,7 +19,7 @@ outputs:
 runs:
   using: 'composite'
   steps:
-    - name: Validate runner OS
+    - name: Validate runner OS and architecture
       shell: bash
       run: |
         if [ "$RUNNER_OS" != "Linux" ]; then
@@ -27,6 +27,13 @@ runs:
           exit 1
         fi
 
+        # Validate architecture (only x64 is supported)
+        ARCH=$(uname -m)
+        if [ "$ARCH" != "x86_64" ] && [ "$ARCH" != "amd64" ]; then
+          echo "::error::This action only supports x64 architecture. Current architecture: $ARCH"
+          exit 1
+        fi
+
     - name: Install awf
       id: install
       shell: bash
@@ -45,17 +52,22 @@ runs:
         # Determine version
         if [ "$INPUT_VERSION" = "latest" ] || [ -z "$INPUT_VERSION" ]; then
           echo "Fetching latest release version..."
-          VERSION=$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest" | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
-          if [ -z "$VERSION" ]; then
+          # Use jq if available, fallback to grep/sed
+          if command -v jq &> /dev/null; then
+            VERSION=$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest" | jq -r '.tag_name')
+          else
+            VERSION=$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest" | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
+          fi
+          if [ -z "$VERSION" ] || [ "$VERSION" = "null" ]; then
             echo "::error::Failed to fetch latest version from GitHub API"
             exit 1
           fi
           echo "Latest version: $VERSION"
         else
           VERSION="$INPUT_VERSION"
-          # Validate version format
-          if ! echo "$VERSION" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
-            echo "::error::Invalid version format: $VERSION. Expected format: v1.0.0"
+          # Validate version format (supports v1.0.0, v1.0.0-beta.1, v1.0.0-rc.1, etc.)
+          if ! echo "$VERSION" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$'; then
+            echo "::error::Invalid version format: $VERSION. Expected format: v1.0.0 or v1.0.0-beta.1"
             exit 1
           fi
         fi
@@ -83,6 +95,13 @@ runs:
 
         # Verify checksum
         echo "Verifying SHA256 checksum..."
+        
+        # Validate checksums.txt format (should have "checksum  filename" format)
+        if ! grep -qE '^[a-fA-F0-9]{64}  ' "$INSTALL_DIR/checksums.txt"; then
+          echo "::error::checksums.txt has unexpected format"
+          exit 1
+        fi
+        
         EXPECTED_SUM=$(awk -v fname="$BINARY_NAME" '$2 == fname {print $1; exit}' "$INSTALL_DIR/checksums.txt")
 
         if [ -z "$EXPECTED_SUM" ]; then
@@ -97,8 +116,8 @@ runs:
         fi
 
         # Normalize to lowercase for comparison
-        EXPECTED_SUM=$(echo "$EXPECTED_SUM" | tr 'A-F' 'a-f')
-        ACTUAL_SUM=$(sha256sum "$INSTALL_DIR/awf" | awk '{print $1}' | tr 'A-F' 'a-f')
+        EXPECTED_SUM=$(echo "$EXPECTED_SUM" | tr '[:upper:]' '[:lower:]')
+        ACTUAL_SUM=$(sha256sum "$INSTALL_DIR/awf" | awk '{print $1}' | tr '[:upper:]' '[:lower:]')
 
         if [ "$EXPECTED_SUM" != "$ACTUAL_SUM" ]; then
           echo "::error::Checksum verification failed!"

From 30fa05acd53dfb7e8fd832e8e9e4d8befcfd0e59 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 5 Jan 2026 23:23:26 +0000
Subject: [PATCH 4/5] ci: add workflow to test setup action

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
---
 .github/workflows/test-action.yml | 82 +++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 .github/workflows/test-action.yml

diff --git a/.github/workflows/test-action.yml b/.github/workflows/test-action.yml
new file mode 100644
index 000000000..857cf7e7d
--- /dev/null
+++ b/.github/workflows/test-action.yml
@@ -0,0 +1,82 @@
+name: Test Setup Action
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test-action-latest:
+    name: Test Action (Latest Version)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4
+
+      - name: Setup awf using action
+        id: setup-awf
+        uses: ./
+
+      - name: Verify awf is installed
+        run: |
+          echo "Installed version: ${{ steps.setup-awf.outputs.version }}"
+          which awf
+          awf --version
+          awf --help
+
+  test-action-specific-version:
+    name: Test Action (Specific Version)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4
+
+      - name: Setup awf using action with specific version
+        id: setup-awf
+        uses: ./
+        with:
+          version: 'v0.7.0'
+
+      - name: Verify awf is installed with correct version
+        run: |
+          echo "Installed version: ${{ steps.setup-awf.outputs.version }}"
+          which awf
+          awf --version
+          # Verify the version matches
+          if [[ "${{ steps.setup-awf.outputs.version }}" != "v0.7.0" ]]; then
+            echo "::error::Version mismatch! Expected v0.7.0, got ${{ steps.setup-awf.outputs.version }}"
+            exit 1
+          fi
+
+  test-action-invalid-version:
+    name: Test Action (Invalid Version - Should Fail)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4
+
+      - name: Setup awf with invalid version (should fail)
+        id: setup-awf
+        uses: ./
+        with:
+          version: 'invalid-version'
+        continue-on-error: true
+
+      - name: Verify action failed as expected
+        run: |
+          if [[ "${{ steps.setup-awf.outcome }}" == "success" ]]; then
+            echo "::error::Action should have failed with invalid version"
+            exit 1
+          fi
+          echo "Action correctly rejected invalid version format"

From d8fc83287e5ce2b300c1a3a413af5c5a2e7ef595 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 5 Jan 2026 23:31:11 +0000
Subject: [PATCH 5/5] feat: add image pinning support to setup action

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
---
 .github/workflows/test-action.yml | 34 +++++++++++++++++++++++++++
 README.md                         | 23 ++++++++++++++++--
 action.yml                        | 39 +++++++++++++++++++++++++++++++
 docs/github_actions.md            | 38 +++++++++++++++++++++++++++++-
 4 files changed, 131 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/test-action.yml b/.github/workflows/test-action.yml
index 857cf7e7d..e84d19d9c 100644
--- a/.github/workflows/test-action.yml
+++ b/.github/workflows/test-action.yml
@@ -49,6 +49,7 @@ jobs:
       - name: Verify awf is installed with correct version
         run: |
           echo "Installed version: ${{ steps.setup-awf.outputs.version }}"
+          echo "Image tag: ${{ steps.setup-awf.outputs.image-tag }}"
           which awf
           awf --version
           # Verify the version matches
@@ -56,6 +57,39 @@ jobs:
             echo "::error::Version mismatch! Expected v0.7.0, got ${{ steps.setup-awf.outputs.version }}"
             exit 1
           fi
+          # Verify image tag is set correctly (without 'v' prefix)
+          if [[ "${{ steps.setup-awf.outputs.image-tag }}" != "0.7.0" ]]; then
+            echo "::error::Image tag mismatch! Expected 0.7.0, got ${{ steps.setup-awf.outputs.image-tag }}"
+            exit 1
+          fi
+
+  test-action-with-images:
+    name: Test Action (With Image Pull)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4
+
+      - name: Setup awf with image pull
+        id: setup-awf
+        uses: ./
+        with:
+          version: 'v0.7.0'
+          pull-images: 'true'
+
+      - name: Verify awf and images are available
+        run: |
+          echo "Installed version: ${{ steps.setup-awf.outputs.version }}"
+          echo "Image tag: ${{ steps.setup-awf.outputs.image-tag }}"
+          which awf
+          awf --version
+          
+          # Verify Docker images are pulled
+          echo "Checking for pulled images..."
+          docker images ghcr.io/githubnext/gh-aw-firewall/squid
+          docker images ghcr.io/githubnext/gh-aw-firewall/agent
 
   test-action-invalid-version:
     name: Test Action (Invalid Version - Should Fail)
diff --git a/README.md b/README.md
index 3e74af02c..0798e05e0 100644
--- a/README.md
+++ b/README.md
@@ -42,13 +42,32 @@ Use the setup action in your workflows:
 steps:
   - name: Setup awf
     uses: githubnext/gh-aw-firewall@main
-    # with:
-    #   version: 'v1.0.0'  # Optional: defaults to latest
+    with:
+      # version: 'v1.0.0'    # Optional: defaults to latest
+      # pull-images: 'true'  # Optional: pre-pull Docker images for the version
 
   - name: Run command with firewall
     run: sudo awf --allow-domains github.com -- curl https://api.github.com
 ```
 
+To pin Docker images to match the installed version, use `pull-images: 'true'` and pass the image tag to awf:
+
+```yaml
+steps:
+  - name: Setup awf
+    id: setup-awf
+    uses: githubnext/gh-aw-firewall@main
+    with:
+      version: 'v0.7.0'
+      pull-images: 'true'
+
+  - name: Run with pinned images
+    run: |
+      sudo awf --allow-domains github.com \
+        --image-tag ${{ steps.setup-awf.outputs.image-tag }} \
+        -- curl https://api.github.com
+```
+
 #### Shell script
 
 ```bash
diff --git a/action.yml b/action.yml
index 30f4b001f..b76071eaa 100644
--- a/action.yml
+++ b/action.yml
@@ -10,11 +10,18 @@ inputs:
     description: 'Version to install (e.g., v1.0.0). Defaults to latest release.'
     required: false
     default: 'latest'
+  pull-images:
+    description: 'Pull Docker images for the installed version. Set to "true" to pre-pull squid and agent images.'
+    required: false
+    default: 'false'
 
 outputs:
   version:
     description: 'The version of awf that was installed'
     value: ${{ steps.install.outputs.version }}
+  image-tag:
+    description: 'The image tag that matches the installed version (without the v prefix)'
+    value: ${{ steps.install.outputs.image_tag }}
 
 runs:
   using: 'composite'
@@ -73,6 +80,10 @@ runs:
         fi
 
         echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+        
+        # Extract image tag (version without 'v' prefix)
+        IMAGE_TAG="${VERSION#v}"
+        echo "image_tag=$IMAGE_TAG" >> "$GITHUB_OUTPUT"
 
         # Download URLs
         BASE_URL="https://github.com/${REPO}/releases/download/${VERSION}"
@@ -145,3 +156,31 @@ runs:
 
         echo "Successfully installed awf ${VERSION} to $INSTALL_DIR"
         echo "awf is now available in PATH for subsequent steps"
+
+    - name: Pull Docker images
+      if: ${{ inputs.pull-images == 'true' }}
+      shell: bash
+      env:
+        IMAGE_TAG: ${{ steps.install.outputs.image_tag }}
+      run: |
+        set -euo pipefail
+        
+        REGISTRY="ghcr.io/githubnext/gh-aw-firewall"
+        
+        echo "Pulling awf Docker images with tag: ${IMAGE_TAG}"
+        
+        # Pull squid image
+        echo "Pulling ${REGISTRY}/squid:${IMAGE_TAG}..."
+        if ! docker pull "${REGISTRY}/squid:${IMAGE_TAG}"; then
+          echo "::warning::Failed to pull squid image with tag ${IMAGE_TAG}, trying 'latest'"
+          docker pull "${REGISTRY}/squid:latest"
+        fi
+        
+        # Pull agent image
+        echo "Pulling ${REGISTRY}/agent:${IMAGE_TAG}..."
+        if ! docker pull "${REGISTRY}/agent:${IMAGE_TAG}"; then
+          echo "::warning::Failed to pull agent image with tag ${IMAGE_TAG}, trying 'latest'"
+          docker pull "${REGISTRY}/agent:latest"
+        fi
+        
+        echo "Docker images pulled successfully ✓"
diff --git a/docs/github_actions.md b/docs/github_actions.md
index 320ae7047..f33d2eff7 100644
--- a/docs/github_actions.md
+++ b/docs/github_actions.md
@@ -11,7 +11,8 @@ steps:
   - name: Setup awf
     uses: githubnext/gh-aw-firewall@main
     # with:
-    #   version: 'v1.0.0'  # Optional: defaults to latest
+    #   version: 'v1.0.0'    # Optional: defaults to latest
+    #   pull-images: 'true'  # Optional: pre-pull Docker images
 
   - name: Run command with firewall
     run: sudo awf --allow-domains github.com -- curl https://api.github.com
@@ -21,6 +22,41 @@ The action:
 - Downloads the specified version (or latest) from GitHub releases
 - Verifies SHA256 checksum
 - Installs to PATH for subsequent steps
+- Optionally pre-pulls Docker images for the installed version
+
+#### Action Inputs
+
+| Input | Description | Default |
+|-------|-------------|---------|
+| `version` | Version to install (e.g., `v1.0.0`) | `latest` |
+| `pull-images` | Pre-pull Docker images for the version | `false` |
+
+#### Action Outputs
+
+| Output | Description |
+|--------|-------------|
+| `version` | The version that was installed (e.g., `v0.7.0`) |
+| `image-tag` | The image tag matching the version (e.g., `0.7.0`) |
+
+#### Pinning Docker Image Versions
+
+For reproducible builds, you can pin both the awf binary and Docker images:
+
+```yaml
+steps:
+  - name: Setup awf
+    id: setup-awf
+    uses: githubnext/gh-aw-firewall@main
+    with:
+      version: 'v0.7.0'
+      pull-images: 'true'
+
+  - name: Run with pinned images
+    run: |
+      sudo awf --allow-domains github.com \
+        --image-tag ${{ steps.setup-awf.outputs.image-tag }} \
+        -- curl https://api.github.com
+```
 
 ### Using the Install Script