Docker Agent Action

A GitHub Action for running Docker Agent AI agents in your workflows. This action simplifies the setup and execution of Docker Agent, handling binary downloads and environment configuration automatically.

Quick Start

1. Add the action to your workflow:

   - uses: docker/docker-agent-action@VERSIONwith:
   agent: path/to/agent.yamlprompt: "Analyze this code"anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

2. Configure API key in your repository settings:

   • Go to Settings → Secrets and variables → Actions
   • Add ANTHROPIC_API_KEY (or another provider's key) from Anthropic Console

3. That's it! The action will automatically:

   • Download the Docker Agent binary
   • Run your specified agent
   • Scan outputs for leaked secrets
   • Provide results in workflow logs

🔒 Security Features

This action includes built-in security features for all agent executions:

• Secret Leak Prevention: Scans all agent outputs for API keys and tokens (Anthropic, OpenAI, GitHub)
• Prompt Injection Detection: Warns about suspicious patterns in user prompts
• Automatic Incident Response: Creates security issues and fails workflows when secrets are detected

To report a vulnerability, see our Security Policy.

Usage

Using a Local Agent File

- name: Run Custom Agentuses: docker/docker-agent-action@VERSIONwith:
agent: ./agents/my-agent.yamlprompt: "Analyze the codebase"anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

Advanced Configuration

- name: Run Docker Agent with Custom Settingsuses: docker/docker-agent-action@VERSIONwith:
agent: docker/code-analyzerprompt: "Analyze this codebase"anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}mcp-gateway: true # Set to true to install mcp-gatewaymcp-gateway-version: v0.22.0yolo: false # Require manual approvaltimeout: 600# 10 minute timeoutdebug: true # Enable debug loggingworking-directory: ./srcextra-args: "--verbose"add-prompt-files: "AGENTS.md,CLAUDE.md"# Append these files to the prompt

Using Outputs

- name: Run Docker Agentid: agentuses: docker/docker-agent-action@VERSIONwith:
agent: docker/code-analyzerprompt: "Analyze this codebase"anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
- name: Check execution timerun: | 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 logif: always()uses: actions/upload-artifact@v4with:
name: agent-outputpath: ${{ steps.agent.outputs.output-file }}

Inputs

Input	Description	Required	Default
agent	Agent identifier (e.g., docker/code-analyzer) or path to .yaml file	Yes	-
prompt	Prompt to pass to the agent	No	-
mcp-gateway	Install mcp-gateway (true/false)	No	false
mcp-gateway-version	Version of mcp-gateway to use (specifying this will enable mcp-gateway installation)	No	v0.22.0
anthropic-api-key	Anthropic API key for Claude models (at least one API key required)	No*	-
openai-api-key	OpenAI API key (at least one API key required)	No*	-
google-api-key	Google API key for Gemini models (at least one API key required)	No*	-
aws-bearer-token-bedrock	AWS Bearer token for Bedrock models (at least one API key required)	No*	-
xai-api-key	xAI API key for Grok models (at least one API key required)	No*	-
nebius-api-key	Nebius API key (at least one API key required)	No*	-
mistral-api-key	Mistral API key (at least one API key required)	No*	-
github-token	GitHub token for API access	No	github.token
timeout	Timeout in seconds for agent execution (0 for no timeout)	No	0
debug	Enable debug mode with verbose logging (true/false)	No	false
working-directory	Working directory to run the agent in	No	.
yolo	Auto-approve all prompts (true/false)	No	true
max-retries	Maximum number of retries on failure (0 = no retries)	No	2
retry-delay	Base delay in seconds between retries (doubles each attempt)	No	5
total-timeout	Total wall-clock budget in seconds across all attempts and retry delays (0 = unlimited)	No	0
no-retry-pattern	Regex tested against the agent log after a failed attempt; on match, retries are skipped	No	-
extra-args	Additional arguments to pass to docker agent run	No	-
add-prompt-files	Comma-separated list of files to append to the prompt (e.g., AGENTS.md,CLAUDE.md)	No	-
skip-summary	Skip writing agent output to the job summary (useful when callers write their own)	No	false

Prompt Files (add-prompt-files)

The add-prompt-files input allows you to include additional context files as system messages. This uses Docker Agent's --prompt-file flag under the hood.

File Resolution (handled by Docker Agent):

• Searches up the directory hierarchy (like .gitignore)
• Also checks the home folder (~/)
• Files are added as system messages, not appended to the user prompt

Examples:

# Additional files beyond the auto-discovered AGENTS.md/CLAUDE.mdadd-prompt-files: "CONTRIBUTING.md,docs/REVIEW_GUIDELINES.md"# With custom working directoryworking-directory: ./srcadd-prompt-files: "STYLE_GUIDE.md"# Found via hierarchy search

Outputs

Output	Description
exit-code	Exit code from docker agent run
output-file	Path to the output log file
docker-agent-version	Version of Docker Agent that was used
cagent-version	Version of Docker Agent that was used (deprecated: use docker-agent-version)
mcp-gateway-installed	Whether mcp-gateway was installed (true/false)
execution-time	Agent execution time in seconds
verbose-log-file	Path to the full verbose agent log (includes tool calls)
security-blocked	Whether execution was blocked due to security concerns (true/false)
secrets-detected	Whether secrets were detected in output
prompt-suspicious	Whether suspicious content was stripped from the prompt (true/false)
input-risk-level	Risk level of input (low/medium/high)

API Keys

At least one API key is required. The action validates this at startup and fails fast with a clear error if no API key is provided.

Supported providers:

• Anthropic (anthropic-api-key): Claude models - Get API key
• OpenAI (openai-api-key): GPT models - Get API key
• Google (google-api-key): Gemini models - Get API key
• AWS Bedrock (aws-bearer-token-bedrock): Various models via AWS
• xAI (xai-api-key): Grok models - Get API key
• Nebius (nebius-api-key): Nebius models
• Mistral (mistral-api-key): Mistral models - Get API key

Permissions

For GitHub integration features (commenting on PRs, creating issues), ensure your workflow has appropriate permissions:

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

Examples

Multiple Agents in a Workflow

name: AI Code Reviewon:
pull_request:
types: [opened]jobs:
review:
runs-on: ubuntu-latestpermissions:
contents: readpull-requests: writesteps:
- uses: actions/checkout@v4
- name: Security Reviewuses: docker/docker-agent-action@VERSIONwith:
agent: docker/github-action-security-scannerprompt: "Analyze for security issues"anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
- name: Code Quality Analysisuses: docker/docker-agent-action@VERSIONwith:
agent: docker/code-quality-analyzerprompt: "Analyze code quality and best practices"anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

PR Review Workflow

For comprehensive documentation on setting up AI-powered PR reviews, including features like automatic reviews, requesting a review from docker-agent, feedback learning, and customization options, see the PR Review documentation.

The job that calls the reusable workflow must grant exactly these permissions:

jobs:
review:
uses: docker/docker-agent-action/.github/workflows/review-pr.yml@VERSIONpermissions:
contents: read # Read repository files and PR diffspull-requests: write # Post review commentsissues: write # Create security incident issues if secrets detectedchecks: write # Show review progress as a check runid-token: write # Required for OIDC authentication to AWS Secrets Manageractions: 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.

For external or fork contributor PRs, an org member approves the workflow run and then requests a review from docker-agent via GitHub's native review request UI (no special commands or workflow inputs required). See External and fork contributor PRs.

Manual Trigger with Inputs

name: Manual Agent Runon:
workflow_dispatch:
inputs:
agent:
description: "Agent to run"required: truedefault: "docker/code-analyzer"prompt:
description: "Prompt for the agent"required: truejobs:
run:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- name: Run Agentuses: docker/docker-agent-action@VERSIONwith:
agent: ${{ github.event.inputs.agent }}prompt: ${{ github.event.inputs.prompt }}anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Setting up your development environment
• Running tests
• Submitting pull requests
• Reporting security issues

Please also read our Code of Conduct.

Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions
• 🔒 Security Policy

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Links

• Docker Agent Repository
• MCP Gateway Repository