act-workflow-syntax

# Act - GitHub Actions Workflow Syntax

Use this skill when creating or modifying GitHub Actions workflow files (`.github/workflows/*.yml`). This covers workflow structure, triggers, jobs, steps, and best practices for workflows that work both on GitHub and locally with act.

## Workflow File Structure

Every GitHub Actions workflow follows this basic structure:

```yaml
name: Workflow Name
on: [push, pull_request]  # Triggers

jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Step name
        run: echo "Commands here"
```

### Top-Level Fields

- `name`: Human-readable workflow name (optional but recommended)
- `on`: Trigger events (push, pull_request, workflow_dispatch, etc.)
- `env`: Environment variables available to all jobs
- `jobs`: Map of job definitions
- `permissions`: Token permissions for the workflow

## Workflow Triggers

### Event Triggers

```yaml
# Single event
on: push

# Multiple events
on: [push, pull_request]

# Event with filters
on:
  push:
    branches:
      - main
      - 'releases/**'
    paths:
      - '**.js'
      - '!docs/**'
  pull_request:
    types: [opened, synchronize, reopened]
```

### Manual Triggers

```yaml
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production
```

### Schedule Triggers

```yaml
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9am UTC
```

## Job Configuration

### Basic Job

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test
```

### Job with Environment Variables

```yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      NODE_ENV: production
      API_URL: ${{ secrets.API_URL }}
    steps:
      - run: echo "Deploying to $NODE_ENV"
```

### Job Dependencies

```yaml
jobs:
  build