Docker Agent Action

Quick Start

🔒 Security Features

Usage

Using a Local Agent File

- name: Run Custom Agent
  uses: docker/docker-agent-action@VERSION
  with:
    agent: ./agents/my-agent.yaml
    prompt: "Analyze the codebase"
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

Advanced Configuration

- name: Run Docker Agent with Custom Settings
  uses: docker/docker-agent-action@VERSION
  with:
    agent: docker/code-analyzer
    prompt: "Analyze this codebase"
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
    mcp-gateway: true # Set to true to install mcp-gateway
    mcp-gateway-version: v0.22.0
    yolo: false # Require manual approval
    timeout: 600 # 10 minute timeout
    debug: true # Enable debug logging
    working-directory: ./src
    extra-args: "--verbose"
    add-prompt-files: "AGENTS.md,CLAUDE.md" # Append these files to the prompt

Using Outputs

- name: Run Docker Agent
  id: agent
  uses: docker/docker-agent-action@VERSION
  with:
    agent: docker/code-analyzer
    prompt: "Analyze this codebase"
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

- name: Check execution time
  run: |
    echo "Agent took ${{ steps.agent.outputs.execution-time }} seconds"
    if [ "${{ steps.agent.outputs.execution-time }}" -gt 300 ]; then
      echo "Warning: Agent took longer than 5 minutes"
    fi

- name: Upload output log
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: agent-output
    path: ${{ steps.agent.outputs.output-file }}

Inputs

Prompt Files (add-prompt-files)

# Additional files beyond the auto-discovered AGENTS.md/CLAUDE.md
add-prompt-files: "CONTRIBUTING.md,docs/REVIEW_GUIDELINES.md"

# With custom working directory
working-directory: ./src
add-prompt-files: "STYLE_GUIDE.md"  # Found via hierarchy search

Outputs

API Keys

Permissions

permissions:
  contents: read # Read repository files and PR diffs
  pull-requests: write # Post review comments and approve/request changes
  issues: write # Create security incident issues if secrets are detected in output
  checks: write # (Optional) Show review progress as a check run on the PR
  id-token: write # Required for OIDC authentication to AWS Secrets Manager

Examples

Multiple Agents in a Workflow

name: AI Code Review
on:
  pull_request:
    types: [opened]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4

      - name: Security Review
        uses: docker/docker-agent-action@VERSION
        with:
          agent: docker/github-action-security-scanner
          prompt: "Analyze for security issues"
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Code Quality Analysis
        uses: docker/docker-agent-action@VERSION
        with:
          agent: docker/code-quality-analyzer
          prompt: "Analyze code quality and best practices"
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

PR Review Workflow

jobs:
  review:
    uses: docker/docker-agent-action/.github/workflows/review-pr.yml@VERSION
    permissions:
      contents: read # Read repository files and PR diffs
      pull-requests: write # Post review comments
      issues: write # Create security incident issues if secrets detected
      checks: write # Show review progress as a check run
      id-token: write # Required for OIDC authentication to AWS Secrets Manager
      actions: write # Required since v2.0.3 — review-lock cache cleanup and feedback artifacts

Important

actions: write is required since v2.0.3 (earlier releases needed only actions: read). A called workflow cannot elevate its caller's permissions, so a caller job granting only actions: read fails GitHub's workflow validation at startup — no job even runs. This applies only to callers of the reusable PR-review workflow shown above; workflows using the root docker/docker-agent-action action directly need only the permissions listed earlier. See the PR Review documentation for complete setup, including the two-workflow pattern for fork PRs.

Manual Trigger with Inputs

name: Manual Agent Run
on:
  workflow_dispatch:
    inputs:
      agent:
        description: "Agent to run"
        required: true
        default: "docker/code-analyzer"
      prompt:
        description: "Prompt for the agent"
        required: true

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Agent
        uses: docker/docker-agent-action@VERSION
        with:
          agent: ${{ github.event.inputs.agent }}
          prompt: ${{ github.event.inputs.prompt }}
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

Contributing

Support

License

Links