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