Complete implementation guide for running Claude Code Bot in GitHub Actions with devcontainer.
Always respond in the language used by the user in their request or in previous conversations.
Target Audiences:
- 👤 Human readers: Overview and explanation sections
- 🤖 Claude Code (setup executor): Follow "Setup Execution" section
- 🚀 Claude Bot (runtime): Configuration in system.md
When instructed to "read and execute this gist":
Before beginning setup, ALWAYS create a task list using the TaskCreate tool.
This helps track progress and ensures all steps are completed. Create tasks for:
- Step 0: Create task list (this step)
- Step 1: Check existing files
- Step 1.5: Update existing setup (if applicable)
- Step 2: Download configuration files (for new setup)
- Step 3: Verify CLAUDE_CODE_OAUTH_TOKEN secret
- Step 4: Commit and push changes
- Step 5: Verify workflow file
- Step 6: Run automated verification (REQUIRED)
Mark each task as in_progress when starting and completed when done.
Use the TaskCreate tool to create tasks for all setup steps listed above. Set the activeForm for each task appropriately (e.g., "Creating task list", "Checking existing files", "Updating existing setup", "Running automated verification", etc.).
Before downloading, check for existing files:
# Check for existing Claude Bot setup
if [ -f ".github/workflows/claude-bot.yml" ]; then
echo "⚠️ Existing Claude Bot setup found"
EXISTING_CLAUDE_BOT=true
else
EXISTING_CLAUDE_BOT=false
fi
# Check for existing devcontainer
if [ -d ".devcontainer" ]; then
echo "⚠️ Existing .devcontainer found"
EXISTING_DEVCONTAINER=true
else
EXISTING_DEVCONTAINER=false
fi
# Check for existing .github/claude directory
if [ -d ".github/claude" ]; then
echo "⚠️ .github/claude directory already exists"
fiIf .github/workflows/claude-bot.yml already exists (EXISTING_CLAUDE_BOT=true):
This is an update operation, not a fresh installation. Follow these steps:
echo "📦 Updating existing Claude Bot setup to latest version..."
# Create .github directories if needed
mkdir -p .github/workflows .github/claude
# Download and update ONLY these files:
curl -o .github/workflows/claude-bot.yml https://gist.githubusercontent.com/masuidrive/3bd621d7c64a408fd5a1835302c3cf61/raw/claude-bot.yml
curl -o .github/claude/run-action.sh https://gist.githubusercontent.com/masuidrive/3bd621d7c64a408fd5a1835302c3cf61/raw/run-action.sh
curl -o .github/claude/system.md https://gist.githubusercontent.com/masuidrive/3bd621d7c64a408fd5a1835302c3cf61/raw/system.md
# Make script executable
chmod +x .github/claude/run-action.sh
echo "✅ Updated claude-bot.yml, run-action.sh, and system.md to latest versions"DO NOT update these files (preserve existing configuration):
- ❌
.devcontainer/devcontainer.json- Keep existing devcontainer setup - ❌
.devcontainer/Dockerfile- Keep existing Docker configuration - ❌
.claude/CLAUDE.md- Keep project-specific test instructions
After updating, skip to Step 3 (verify secret) and then Step 4 (commit and push).
Only execute this step if EXISTING_CLAUDE_BOT=false (no existing Claude Bot setup).
Based on existing files:
If NO existing .devcontainer:
- Download all files from this gist (see File Structure below)
- Create directories:
.github/workflows,.github/claude,.devcontainer - Download using curl commands provided in File Structure section
If existing .devcontainer found:
- DO NOT download .devcontainer files
- Instead, follow "Adapting to Existing Devcontainer" section
- Add required commands and Claude CLI to existing setup
- Only download
.github/workflows/claude-bot.yml,.github/claude/run-action.sh, and.github/claude/system.md
Files to download for new setup:
.github/workflows/claude-bot.yml.github/claude/run-action.sh(and make executable).github/claude/system.md.devcontainer/devcontainer.json(if no existing devcontainer).devcontainer/Dockerfile(if no existing devcontainer)
(see verification steps below)
Commit with descriptive message and push to repository
Check that workflow is recognized by GitHub
This step is MANDATORY. Always execute the automated verification.
If gh command is available (which should be checked in Step 1), execute the complete verification script from the "Testing the Setup" section below. This creates a test issue, monitors workflow execution, and verifies the bot responds correctly.
Do not skip this step. The setup is not complete until automated verification passes.
Before completing setup, verify the secret exists using this priority:
-
If
ghcommand is available: Check secret existence via APIgh api repos/OWNER/REPO/actions/secrets | jq -r '.secrets[].name' | grep -q CLAUDE_CODE_OAUTH_TOKEN
- If found: Proceed with commit/push
- If not found: Warn user and provide setup instructions
-
If
.github/workflows/claude.ymlexists: Assume secret is already configured- The existing
claude-code-actionsetup likely has the secret configured - Proceed with commit/push
- The existing
-
If neither condition is met: Warn user
- Inform them to set up
CLAUDE_CODE_OAUTH_TOKENin repository settings - Provide setup instructions
- Still proceed with commit/push (workflow will fail gracefully with clear error)
- Inform them to set up
This setup enables Claude to autonomously handle Issues and Pull Requests by:
- Triggering on
/codeor🤖in Issue/PR comments - Running in a devcontainer with full development environment
- Committing and pushing changes directly to branches
- Providing real-time progress updates via comments
Download and create these files in your repository:
.github/
workflows/
claude-bot.yml ← Download: curl -O https://gist.githubusercontent.com/masuidrive/3bd621d7c64a408fd5a1835302c3cf61/raw/claude-bot.yml
claude/
run-action.sh ← Download: curl -O https://gist.githubusercontent.com/masuidrive/3bd621d7c64a408fd5a1835302c3cf61/raw/run-action.sh
system.md ← Download: curl -O https://gist.githubusercontent.com/masuidrive/3bd621d7c64a408fd5a1835302c3cf61/raw/system.md
.devcontainer/
devcontainer.json ← Download: curl -O https://gist.githubusercontent.com/masuidrive/3bd621d7c64a408fd5a1835302c3cf61/raw/devcontainer.json
Dockerfile ← Download: curl -O https://gist.githubusercontent.com/masuidrive/3bd621d7c64a408fd5a1835302c3cf61/raw/Dockerfile
.claude/
CLAUDE.md ← Project-specific test instructions (create manually)
Direct Download Links:
- claude-bot.yml
- run-action.sh
⚠️ Make executable! - system.md
- devcontainer.json
- Dockerfile
Important Notes:
- Make
run-action.shexecutable:chmod +x .github/claude/run-action.sh - All files include the latest bug fixes (see Troubleshooting section)
- The workflow file uses the correct environment variable passing method
- The script uses
--dangerously-skip-permissionsflag (correct as of 2026-01)
Claude Bot operates autonomously and should complete tasks end-to-end without stopping for user confirmation, unless:
- Explicit user instruction is required (ambiguous requirements, multiple valid approaches)
- Critical decisions that could have significant impact
- Security-sensitive operations
Default behavior: Execute the full task workflow from start to finish.
When implementing tasks:
- Read the full request and understand all requirements
- Plan the complete solution before starting
- Execute all steps including testing and verification
- Wait for test results and validate outputs
- Fix issues if tests fail and retry until all tests pass
- Only stop when the task is fully complete or requires user input
File: .github/workflows/claude-bot.yml
📥 Download
This workflow:
- Triggers on
/codeor🤖in Issue/PR comments, titles, or bodies - Adds 👀 reaction immediately
- Runs Claude Bot in a devcontainer
- Changes reaction to ✅ (success) or ❌ (failure)
- Posts results as comments
Key Features:
- ✅ Correct environment variable passing to devcontainer
- ✅ Creates GitHub event JSON file for the bot
- ✅ Proper permissions set for contents, PRs, and issues
File: .github/claude/run-action.sh
📥 Download
Remember to make it executable:
chmod +x .github/claude/run-action.shThis script:
- Fetches Issue/PR context via GitHub CLI
- Manages git branches and merge conflicts
- Downloads attached images
- Runs Claude Code Bot with proper authentication
- Commits and pushes changes
- Posts results as GitHub comments
- Handles PR creation errors gracefully
Key Features:
- ✅ Uses
--dangerously-skip-permissionsflag (correct!) - ✅ Graceful PR creation error handling
- ✅ Posts manual PR creation instructions on permission errors
- ✅ Progress updates every 30 seconds
File: .github/claude/system.md
📥 Download
This file defines Claude Bot's behavior:
- Two-phase execution (work + report)
- Mandatory test validation
- Commit and push workflows
- Security policies
- Error handling procedures
- Output format requirements
Important sections:
- Autonomous execution rules
- Test validation requirements (MANDATORY)
/tmp/ccbot-result.mdformat (max 3000 chars)- Artifacts policy for images and large outputs
Files:
These configure the development container:
- Based on TypeScript-Node 22 Bookworm image
- Includes git, GitHub CLI, and common utilities
- Installs Claude Code CLI automatically
- Sets up PATH for Claude command
File: .claude/CLAUDE.md
Create this file with your project-specific test commands:
## How to Run Tests
```bash
# Run all tests
# Depending on the project, use one of the following:
# npm test
# pytest
# bundle exec rake test
# go test ./...
# mvn test
---
## Adapting to Existing Devcontainer
If you already have a `.devcontainer/` setup, you need to add the following.
### Required Commands
The following commands must be available in your devcontainer:
- `git` - Version control
- `gh` (GitHub CLI) - GitHub API operations
- `jq` - JSON processing
- `curl` - Downloads and API calls
- `file` - File type detection
- `timeout` - Command timeout control (usually included in coreutils)
If any of these are missing, add them via Dockerfile or devcontainer features.
### Installing Claude Code CLI
Add the following to your existing Dockerfile or devcontainer configuration:
**For Dockerfile:**
```dockerfile
# After switching to non-root user (e.g., USER node, USER vscode)
USER your_user_name
# Install Claude Code CLI
RUN curl -fsSL https://claude.ai/install.sh | bash
# Add to PATH
ENV PATH="/home/your_user_name/.local/bin:${PATH}"
For devcontainer.json:
{
"postCreateCommand": "curl -fsSL https://claude.ai/install.sh | bash && echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bashrc"
}- Install Claude CLI as the same user specified in
remoteUser - Always add
~/.local/binto PATH .github/workflows/claude-bot.ymland.github/claude/directory are required- Set
CLAUDE_CODE_OAUTH_TOKENas a GitHub repository secret
Reference: For a complete configuration example for new setups, download the files from this gist.
After completing the setup and pushing changes, Claude Code can automatically verify the installation using the gh command:
When instructed to verify the setup, execute the complete verification flow automatically:
Complete Verification Script:
#!/bin/bash
set -e
echo "🔍 Starting Claude Bot verification..."
# Step 1: Verify gh command
if ! command -v gh &> /dev/null; then
echo "❌ Error: gh command not found. Please install GitHub CLI."
exit 1
fi
echo "✅ GitHub CLI found: $(gh --version | head -1)"
# Step 2: Create test issue and capture URL
echo ""
echo "📝 Creating test issue..."
ISSUE_URL=$(gh issue create --title "Claude Bot 動作確認テスト" --body "OSのバージョン番号を教えて 🤖")
ISSUE_NUMBER=$(echo "$ISSUE_URL" | grep -o '[0-9]*$')
echo "✅ Test issue created: $ISSUE_URL"
# Step 3: Wait for workflow to start (with timeout)
echo ""
echo "⏳ Waiting for workflow to start..."
WAIT_COUNT=0
MAX_WAIT=30
while [ $WAIT_COUNT -lt $MAX_WAIT ]; do
sleep 3
RUN_ID=$(gh run list --workflow="claude-bot.yml" --limit 1 --json databaseId --jq '.[0].databaseId' 2>/dev/null || echo "")
if [ -n "$RUN_ID" ]; then
echo "✅ Workflow started (Run ID: $RUN_ID)"
break
fi
WAIT_COUNT=$((WAIT_COUNT + 1))
done
if [ -z "$RUN_ID" ]; then
echo "⚠️ Warning: Workflow did not start within 90 seconds"
echo " Check: https://github.com/$(gh repo view --json nameWithOwner -q .nameWithOwner)/actions"
exit 1
fi
# Step 4: Monitor workflow execution with progress updates
echo ""
echo "🔄 Monitoring workflow execution..."
WORKFLOW_URL="https://github.com/$(gh repo view --json nameWithOwner -q .nameWithOwner)/actions/runs/$RUN_ID"
echo " Workflow URL: $WORKFLOW_URL"
ELAPSED=0
while true; do
WORKFLOW_STATUS=$(gh run view $RUN_ID --json status,conclusion --jq '.status' 2>/dev/null || echo "unknown")
if [ "$WORKFLOW_STATUS" = "completed" ]; then
CONCLUSION=$(gh run view $RUN_ID --json conclusion --jq '.conclusion')
echo ""
if [ "$CONCLUSION" = "success" ]; then
echo "✅ Workflow completed successfully!"
else
echo "❌ Workflow failed with conclusion: $CONCLUSION"
fi
break
fi
# Progress update every 30 seconds
if [ $((ELAPSED % 30)) -eq 0 ]; then
echo " Status: $WORKFLOW_STATUS (${ELAPSED}s elapsed...)"
fi
sleep 10
ELAPSED=$((ELAPSED + 10))
# Timeout after 10 minutes
if [ $ELAPSED -gt 600 ]; then
echo "⚠️ Workflow timeout (10 minutes exceeded)"
echo " Check workflow logs: gh run view $RUN_ID --log"
break
fi
done
# Step 5: Display issue comments
echo ""
echo "💬 Claude Bot response:"
echo "----------------------------------------"
gh issue view $ISSUE_NUMBER --comments 2>/dev/null || echo "Could not fetch comments"
echo "----------------------------------------"
# Step 6: Check for errors and display logs if needed
if [ "$CONCLUSION" != "success" ]; then
echo ""
echo "📋 Workflow logs (failed steps):"
echo "----------------------------------------"
gh run view $RUN_ID --log-failed 2>/dev/null || gh run view $RUN_ID --log 2>/dev/null || echo "Could not fetch logs"
echo "----------------------------------------"
fi
# Step 7: Summary report
echo ""
echo "📊 Verification Summary:"
echo " Issue: $ISSUE_URL"
echo " Workflow: $WORKFLOW_URL"
echo " Status: $CONCLUSION"
echo ""
if [ "$CONCLUSION" = "success" ]; then
echo "✅ Claude Bot setup verification completed successfully!"
echo ""
echo "Next steps:"
echo "- Try creating an issue with 🤖 to trigger the bot"
echo "- Or comment '/code' on any existing issue/PR"
else
echo "❌ Verification failed. Please check:"
echo "1. Workflow logs above for error details"
echo "2. Troubleshooting section in the gist"
echo "3. Repository secrets (CLAUDE_CODE_OAUTH_TOKEN)"
fiUsage:
When completing the setup, Claude Code should:
- Save the above script to a temporary file
- Execute it with bash
- Report the results to the user
- Include the issue URL and workflow URL in the final report
Alternative: Step-by-step execution
If you prefer to execute each step individually, use the commands from the script above separately. The integrated script provides better error handling and progress reporting.
- Navigate to your repository on GitHub
- Go to "Issues" and create a new issue
- Add
/codeor🤖emoji to the issue title or body - Wait for the bot to respond
- Check the "Actions" tab to see the workflow execution
- Verify the bot posted results as a comment
Problem: Environment variables not passed to devcontainer.
Fix: The latest claude-bot.yml file (📥 download) already includes the fix.
The workflow exports environment variables within runCmd:
runCmd: |
# Export environment variables in runCmd
export CLAUDE_CODE_OAUTH_TOKEN="${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}"
export GITHUB_TOKEN="${{ secrets.GITHUB_TOKEN }}"
export GITHUB_REPOSITORY="${{ github.repository }}"
export GITHUB_EVENT_NAME="${{ github.event_name }}"
# Create event JSON file
cat > /tmp/github_event.json << 'EVENTEOF'
${{ toJSON(github.event) }}
EVENTEOF
export GITHUB_EVENT_PATH="/tmp/github_event.json"
cd /workspaces/*
bash .github/claude/run-action.shProblem: Using wrong flag name.
Fix: The latest run-action.sh file (📥 download) uses the correct flag:
timeout 1800 claude \
--output-format json \
--dangerously-skip-permissions \
<<EOF > "$OUTPUT_FILE" 2>&1Note: The correct flag is --dangerously-skip-permissions.
Problem: Repository settings don't allow GitHub Actions to create PRs.
Fix Option 1 - Enable in Settings (Recommended):
- Go to repository Settings → Actions → General
- Scroll to "Workflow permissions"
- Enable "Allow GitHub Actions to create and approve pull requests"
- Save changes
Fix Option 2 - Handled gracefully in script:
The latest run-action.sh handles this automatically by:
- Catching the PR creation error
- Posting a comment with manual PR creation instructions
- Not failing the workflow
This is already implemented in the provided script.
Possible causes:
- Claude didn't write to
/tmp/ccbot-result.md - No actual file changes were needed
- Claude encountered an error during execution
Check:
- Workflow logs for Claude's output
- Issue comments for error messages
- Ensure the task is clear and actionable
Problem: The grep version in the container doesn't support the regex pattern used for image extraction.
Impact: Minor - image extraction might not work, but this doesn't affect core functionality.
Fix (optional): Use a simpler regex pattern or install GNU grep in the Dockerfile.
When executing this gist, follow this complete flow:
-
✅ Create Task List (REQUIRED)
- Use TaskCreate tool to create tasks for all steps
- Mark tasks as in_progress/completed as you work
- This ensures nothing is skipped
-
✅ Verify Prerequisites
- Check if
ghcommand is available - Check if
CLAUDE_CODE_OAUTH_TOKENsecret exists
- Check if
-
✅ Create Files
- Download and create all files from this gist (see File Structure section)
- Make
run-action.shexecutable:chmod +x .github/claude/run-action.sh
-
✅ Commit and Push
git add . git commit -m "🤖 Add Claude Code Bot - GitHub Actions integration" git push
-
✅ Verify Workflow
gh workflow list
-
✅ Run Automated Test (REQUIRED)
This step is MANDATORY - do not skip.
Execute the complete verification script from the "Testing the Setup" section. The script will:
- Create a test issue with 🤖
- Wait for workflow to start
- Monitor execution progress
- Display bot's response
- Report success/failure
Do not proceed to step 6 until this test passes.
-
✅ Report Results
- If test successful: Confirm setup is complete
- If test failed: Report specific errors and fixes applied
- Always show the test issue URL and workflow run URL
Trigger the bot:
- Comment
/codeor🤖on any Issue or PR
Monitor execution:
gh run list --workflow="claude-bot.yml" --limit 5
gh run view [RUN_ID] --logCheck bot responses:
gh issue view [ISSUE_NUMBER] --commentsEnable PR creation: Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests"
Required secrets:
CLAUDE_CODE_OAUTH_TOKEN(required)GITHUB_TOKEN(automatic)
Download all files:
# Create directories
mkdir -p .github/workflows .github/claude .devcontainer
# Download files
curl -o .github/workflows/claude-bot.yml https://gist.githubusercontent.com/masuidrive/3bd621d7c64a408fd5a1835302c3cf61/raw/claude-bot.yml
curl -o .github/claude/run-action.sh https://gist.githubusercontent.com/masuidrive/3bd621d7c64a408fd5a1835302c3cf61/raw/run-action.sh
curl -o .github/claude/system.md https://gist.githubusercontent.com/masuidrive/3bd621d7c64a408fd5a1835302c3cf61/raw/system.md
curl -o .devcontainer/devcontainer.json https://gist.githubusercontent.com/masuidrive/3bd621d7c64a408fd5a1835302c3cf61/raw/devcontainer.json
curl -o .devcontainer/Dockerfile https://gist.githubusercontent.com/masuidrive/3bd621d7c64a408fd5a1835302c3cf61/raw/Dockerfile
# Make script executable
chmod +x .github/claude/run-action.shFor issues or questions, check the GitHub Actions logs first, then refer to the Troubleshooting section above.