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 }})