Simple Forge GitHub Actions

Execute Claude-powered code generation workflows for GitHub issues with Simple Forge. This repository provides two GitHub Actions that integrate with the Simple Forge service to automate code generation, issue processing, and workflow orchestration.

🚀 Quick Start

Docker Action (Recommended)

- name: Run Simple Forge
  uses: simple-container-com/forge-action/.github/actions@v1
  with:
    job_id: ${{ inputs.job_id }}
    issue_id: ${{ inputs.issue_id }}
    service_url: 'https://forge.simple-container.com'
    model_name: 'claude-sonnet-4-5'
    branch: ${{ inputs.branch }}
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    anthropic_base_url: ${{ secrets.ANTHROPIC_BASE_URL || format('{0}/ai', inputs.service_url || 'https://forge.simple-container.com') || 'https://api.anthropic.com' }}
    simple_forge_api_key: ${{ secrets.SIMPLE_FORGE_API_KEY }}
    github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

Dockerless Action (For Docker-restricted environments)

- name: Run Simple Forge (Dockerless)
  uses: simple-container-com/forge-action/.github/actions/dockerless@v1
  with:
    job_id: ${{ inputs.job_id }}
    issue_id: ${{ inputs.issue_id }}
    service_url: 'https://forge.simple-container.com'
    branch: ${{ inputs.branch }}
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    anthropic_base_url: ${{ secrets.ANTHROPIC_BASE_URL || format('{0}/ai', inputs.service_url || 'https://forge.simple-container.com') || 'https://api.anthropic.com' }}
    simple_forge_api_key: ${{ secrets.SIMPLE_FORGE_API_KEY }}
    github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
    script_version: 'latest'

📋 Actions Overview

This repository provides two GitHub Actions:

Action	Path	Use Case	Requirements
Docker Action	/	Production use, faster execution	Docker support
Dockerless Action	/dockerless	Docker-restricted environments	Docker for script extraction

🔧 Action Specifications

Docker Action (action.yml)

The main action that runs in a pre-built Docker container with all dependencies included.

Inputs

Input	Description	Required	Default
job_id	Job ID from the Simple Forge queue	✅	-
issue_id	GitHub issue ID to process	✅	-
service_url	Simple Forge service URL	❌	https://forge.simple-container.com
model_name	Claude model to use for generation	❌	claude-sonnet-4-5
branch	Target branch for changes	✅	-
anthropic_api_key	Anthropic API key for Claude	✅	-
anthropic_base_url	Anthropic API base URL (supports AI gateway)	❌	https://api.anthropic.com
simple_forge_api_key	Simple Forge API key	✅	-
github_token	GitHub Personal Access Token for repository access	✅	-

Outputs

Output	Description
status	Workflow execution status
branch	Branch where changes were made
workflow_url	URL to the workflow run

Dockerless Action (dockerless/action.yml)

A composite action that runs without Docker containers, extracting scripts from the Docker image at runtime.

Inputs

Input	Description	Required	Default
job_id	Job ID from the Simple Forge queue	✅	-
issue_id	GitHub issue ID to process	✅	-
service_url	Simple Forge service URL	❌	https://forge.simple-container.com
branch	Target branch for changes	✅	-
anthropic_api_key	Anthropic API key for Claude	✅	-
anthropic_base_url	Anthropic API base URL (supports AI gateway)	❌	https://api.anthropic.com
simple_forge_api_key	Simple Forge API key	✅	-
github_token	GitHub Personal Access Token for repository access	✅	-
script_version	Version of scripts to use	❌	latest
skip_dependency_install	Skip automatic dependency installation	❌	false

Outputs

Output	Description
status	Workflow execution status
branch	Branch where changes were made
workflow_url	URL to the workflow run

📖 Complete Workflow Examples

Basic Workflow with Docker Action

name: Simple Forge Workflow
on:
  workflow_dispatch:
    inputs:
      job_id:
        description: 'Job ID from the queue'
        required: true
        type: string
      issue_id:
        description: 'GitHub issue ID'
        required: true
        type: string
      branch:
        description: 'Target branch for changes'
        required: true
        type: string
      service_url:
        description: 'Simple Forge service URL'
        required: false
        type: string
        default: 'https://forge.simple-container.com'
      model_name:
        description: 'Claude model to use for generation'
        required: false
        default: 'claude-sonnet-4-5'
      script_version:
        description: 'Script version to use'
        required: false
        type: string
        default: 'latest'
      api_token:
        description: 'JWT token for both AI gateway and forge service API access'
        required: false
        type: string

jobs:
  generate-code:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    
    steps:
    - name: Run Simple Forge
      uses: simple-container-com/forge-action/.github/actions@v1
      with:
        job_id: ${{ inputs.job_id }}
        issue_id: ${{ inputs.issue_id }}
        service_url: "${{ inputs.service_url || 'https://forge.simple-container.com' }}"
        model_name: ${{ inputs.model_name }}
        branch: ${{ inputs.branch }}
        anthropic_api_key: ${{ inputs.api_token || secrets.ANTHROPIC_API_KEY }}
        anthropic_base_url: ${{ secrets.ANTHROPIC_BASE_URL || format('{0}/ai', inputs.service_url || 'https://forge.simple-container.com') || 'https://api.anthropic.com' }}
        simple_forge_api_key: ${{ inputs.api_token || secrets.SIMPLE_FORGE_API_KEY }}
        github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

Advanced Workflow with Dockerless Action

name: Simple Forge Workflow (Dockerless)
on:
  workflow_dispatch:
    inputs:
      job_id:
        description: 'Job ID from the queue'
        required: true
        type: string
      issue_id:
        description: 'GitHub issue ID'
        required: true
        type: string
      branch:
        description: 'Target branch for changes'
        required: true
        type: string
      service_url:
        description: 'Simple Forge service URL'
        required: false
        type: string
        default: 'https://forge.simple-container.com'
      model_name:
        description: 'Claude model to use for generation'
        required: false
        default: 'claude-sonnet-4-5'
      script_version:
        description: 'Script version to use'
        required: false
        type: string
        default: 'latest'
      api_token:
        description: 'JWT token for both AI gateway and forge service API access'
        required: false
        type: string

jobs:
  generate-code:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    
    steps:
    - name: Checkout repository
      uses: actions/checkout@v4
      with:
        token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
        fetch-depth: 0
        
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '22'
        
    - name: Setup Go
      uses: actions/setup-go@v5
      with:
        go-version: '1.22'
        
    - name: Run Simple Forge (Dockerless)
      uses: simple-container-com/forge-action/.github/actions/dockerless@v1
      with:
        job_id: ${{ inputs.job_id }}
        issue_id: ${{ inputs.issue_id }}
        service_url: "${{ inputs.service_url || 'https://forge.simple-container.com' }}"
        branch: ${{ inputs.branch }}
        model_name: ${{ inputs.model_name }}
        anthropic_api_key: ${{ inputs.api_token || secrets.ANTHROPIC_API_KEY }}
        anthropic_base_url: ${{ secrets.ANTHROPIC_BASE_URL || format('{0}/ai', inputs.service_url || 'https://forge.simple-container.com') || 'https://api.anthropic.com' }}
        simple_forge_api_key: ${{ inputs.api_token || secrets.SIMPLE_FORGE_API_KEY }}
        github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
        script_version: ${{ inputs.script_version }}
        skip_dependency_install: 'false'

🔐 Secrets Configuration

Configure these secrets in your repository settings:

Secret	Description	Required
PERSONAL_ACCESS_TOKEN	GitHub Personal Access Token with repository access	✅ Required
ANTHROPIC_API_KEY	Your Anthropic API key for Claude access (fallback when api_token not provided)	❌ Optional
SIMPLE_FORGE_API_KEY	Your Simple Forge service API key (fallback when api_token not provided)	❌ Optional
ANTHROPIC_BASE_URL	Custom Anthropic API base URL (for AI gateways)	❌ Optional

Setting up Secrets

1. Go to your repository Settings → Secrets and variables → Actions
2. Click New repository secret
3. Add the required PERSONAL_ACCESS_TOKEN and any optional secrets you need

PERSONAL_ACCESS_TOKEN Requirements

Your GitHub Personal Access Token must have the following permissions:

• Contents: Write (to create/modify files)
• Pull requests: Write (to create pull requests)
• Metadata: Read (to access repository information)
• Actions: Read (for workflow access)

For classic tokens, ensure these scopes are selected:

• repo (full repository access)
• workflow (if updating workflow files)

API Credentials

Primary Method: api_token workflow input (Recommended)

• Pass a JWT token that works for both Anthropic and Simple Forge APIs
• Provide api_token as a workflow input when triggering the workflow
• No repository secrets needed for API access

Fallback Method: Individual secrets (Optional)

• ANTHROPIC_API_KEY and SIMPLE_FORGE_API_KEY are used only when api_token is not provided
• Useful for backward compatibility or alternative authentication methods

ANTHROPIC_BASE_URL (Optional)

This secret allows you to use AI gateways or custom Anthropic API endpoints. If not provided, the action will automatically use:

1. Your custom ANTHROPIC_BASE_URL if set
2. The Simple Forge AI gateway at {service_url}/ai
3. The default Anthropic API at https://api.anthropic.com

🛠️ Setup Requirements

For Docker Action

• GitHub Actions runner with Docker support
• No additional setup required

For Dockerless Action

• GitHub Actions runner (any)
• Docker available for script extraction (temporary)
• Node.js and Go setup (if not using skip_dependency_install)

🎯 Use Cases

When to Use Docker Action

• ✅ Production environments
• ✅ Faster execution (pre-built container)
• ✅ Consistent environment
• ✅ Minimal setup required

When to Use Dockerless Action

• ✅ Docker-restricted environments
• ✅ Custom dependency management
• ✅ Debugging and development
• ✅ Environments with Docker limitations

🔄 Workflow Process

Both actions follow the same workflow process:

1. Environment Setup - Configure workspace and dependencies
2. Branch Management - Create or switch to target branch
3. Context Fetching - Retrieve job context from Simple Forge service
4. Claude Setup - Initialize Claude CLI and plugins
5. Code Generation - Execute Claude-powered code generation
6. Response Processing - Process and validate generated code
7. Change Commitment - Commit and push changes to repository
8. Status Reporting - Report completion status to Simple Forge service

📊 Monitoring and Debugging

Action Outputs

Both actions provide structured outputs for monitoring:

- name: Run Simple Forge
  id: forge
  uses: simple-container-com/forge-action/.github/actions@v1
  with:
    # ... inputs

- name: Check Results
  run: |
    echo "Status: ${{ steps.forge.outputs.status }}"
    echo "Branch: ${{ steps.forge.outputs.branch }}"
    echo "Workflow URL: ${{ steps.forge.outputs.workflow_url }}"

Debug Mode

Enable debug logging by setting the ACTIONS_STEP_DEBUG secret to true in your repository.

🚨 Troubleshooting

Common Issues

Authentication Errors

Error: API authentication failed

Solution: Verify your SIMPLE_FORGE_API_KEY and ANTHROPIC_API_KEY secrets are correctly set.

Branch Creation Failures

Error: Failed to create branch

Solution: Ensure your PERSONAL_ACCESS_TOKEN has sufficient permissions for the repository.

Docker Pull Failures (Dockerless Action)

Error: Failed to pull Docker image

Solution: Check Docker availability and network connectivity on the runner.

Script Extraction Failures (Dockerless Action)

Error: Critical scripts are missing

Solution: Verify the Docker image version and ensure script extraction completed successfully.

Getting Help

1. Check the workflow run logs for detailed error information
2. Verify all required secrets are properly configured
3. Ensure your Simple Forge service is accessible and responsive
4. Review the Simple Forge documentation for service-specific issues

🔗 Related Resources

• Simple Forge Service Documentation
• Anthropic Claude API Documentation
• GitHub Actions Documentation

📄 License

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

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines for details on how to submit pull requests, report issues, and contribute to the project.

---

Simple Forge - Automate your code generation workflows with Claude AI