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'