action-builder

Action Builder

Build custom GitHub Actions for reusable workflow logic.

Quick Start

Choose action type based on requirements:

• Composite: Combine multiple workflow steps (simplest, no code)
• Docker: Run containerized logic (any language, slower startup)
• JavaScript: Fast execution, Node.js required

Instructions

Step 1: Choose Action Type

Use Composite when:

• Combining existing actions and shell commands
• No custom code needed
• Fast execution required
• Example: Setup environment with multiple tools

Use Docker when:

• Need specific runtime environment
• Using non-JavaScript languages
• Complex dependencies
• Example: Custom linting tool, data processing

Use JavaScript when:

• Need programmatic control
• Fast startup time critical
• Interacting with GitHub API
• Example: Issue labeler, PR validator

Step 2: Create Action Structure

All action types need:

action-name/
├── action.yml          # Action metadata
├── README.md           # Documentation
└── [implementation]    # Type-specific files

Step 3: Define action.yml

Required fields:

name: 'Action Name'
description: 'What the action does'
author: 'Your Name'

inputs:
  input-name:
    description: 'Input description'
    required: true
    default: 'default-value'

outputs:
  output-name:
    description: 'Output description'
    value: ${{ steps.step-id.outputs.output-name }}

runs:
  using: 'composite|docker|node16'
  # Type-specific configuration

Step 4: Implement Action Logic

For Composite Actions:

runs:
  using: 'composite'
  steps:
    - name: Step name
      run: echo "Command"
      shell: bash
    - uses: actions/checkout@v3

For Docker Actions:

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.input-name }}

For JavaScript Actions:

runs:
  using: 'node16'
  main: 'dist/index.js'

Step 5: Test Action Locally

Test in workflow:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ./  # Test local action
        with:
          input-name: 'test-value'

Step 6: Version and Publish

Versioning:

• Use semantic versioning (v1.0.0)
• Create Git tags for releases
• Maintain major version tags (v1, v2)

Publishing:

• Push to GitHub repository
• Create release with tag
• Add to GitHub Marketplace (optional)

Common Patterns

Input Validation

inputs:
  environment:
    description: 'Deployment environment'
    required: true
  region:
    description: 'AWS region'
    required: false
    default: 'us-east-1'

Output Setting

Composite:

echo "output-name=value" >> $GITHUB_OUTPUT

JavaScript:

core.setOutput('output-name', 'value');

Error Handling

Composite:

if [ $? -ne 0 ]; then
  echo "::error::Operation failed"
  exit 1
fi

JavaScript:

try {
  // Action logic
} catch (error) {
  core.setFailed(error.message);
}

Advanced

For detailed implementation guides:

• Composite Actions - Multi-step workflows
• Docker Actions - Containerized actions
• Inputs and Outputs - Data handling patterns

Troubleshooting

Action not found:

• Verify action.yml exists in repository root
• Check action path in workflow (uses: owner/repo@version)

Inputs not working:

• Confirm input names match action.yml
• Check required vs. optional inputs
• Verify default values

Outputs not available:

• Ensure output is set before job completes
• Check step ID matches output reference
• Verify output syntax (${{ steps.id.outputs.name }})