/github-actions

name: github-actions
description: >
  Use this skill when authoring or debugging GitHub Actions workflows
  (.github/workflows/*.yml) — e.g. "add CI for this Drupal project on
  GitHub", "run phpcs/phpstan/phpunit on pull requests", "cache composer
  dependencies", "deploy over SSH when main is pushed", "why didn't my
  workflow trigger", or anything involving jobs, matrices, runners, secrets,
  or reusable workflows.

GitHub Actions Skill

GitHub Actions runs workflows from `.github/workflows/*.yml`. This skill covers workflow authoring with a Drupal project as the working example: linting, static analysis, PHPUnit with a database service, and SSH/drush deployment.

---

Workflow anatomy

name: CI

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read            # least privilege — grant more only per job

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true  # newer push cancels the outdated run

jobs:
  phpcs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          tools: composer:v2
      - uses: actions/cache@v4
        with:
          path: ~/.composer/cache
          key: composer-${{ hashFiles('composer.lock') }}
          restore-keys: composer-
      - run: composer install --no-progress
      - run: vendor/bin/phpcs --standard=Drupal,DrupalPractice web/modules/custom

Key defaults to always set:

• **`permissions:`** — the implicit token is powerful; start from

`contents: read` and widen per job only when needed.

• **`concurrency:`** — avoids burning runner minutes on superseded pushes.

---

PHPUnit with a database service

  phpunit:
    runs-on: ubuntu-latest
    services:
      db:
        image: mariadb:11.4
        env:
          MARIADB_DATABASE: drupal_test
          MARIADB_ROOT_PASSWORD: root
        ports: ['3306:3306']
        options: >-
          --health-cmd="healthcheck.sh --connect --innodb_initialized"
          --health-interval=10s --health-timeout=5s --health-retries=5
    env:
      SIMPLETEST_DB: mysql://root:root@127.0.0.1:3306/drupal_test
      SIMPLETEST_BASE_URL: http://localhost
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          extensions: gd, pdo_mysql
      - run: composer install --no-progress
      - run: vendor/bin/phpunit -c web/core/phpunit.xml.dist web/modules/custom

`services:` containers get health-checked before steps run — no manual wait loops. From the runner they are reachable on `127.0.0.1:<mapped port>`.

Matrix builds

    strategy:
      matrix:
        php: ['8.3', '8.4']
    steps:
      - uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}

---

Deployment job

  deploy:
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    needs: [phpcs, phpunit]
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://www.example.com
    steps:
      - uses: webfactory/ssh-agent@v0.9.0
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
      - run: |
          ssh -o StrictHostKeyChecking=accept-new deploy@prod.example.com \
            "cd /var/www/site && git pull --ff-only \
             && composer install --no-dev --optimize-autoloader \
             && vendor/bin/drush deploy -y"

• `needs:` gates deployment on green checks.
• `environment:` enables required reviewers and deployment history

(Settings → Environments) — use it for production approval gates.

• Secrets live in repo/environment settings, referenced via

`${{ secrets.NAME }}`. For cloud providers prefer **OIDC** (`permissions: id-token: write` + the provider's auth action) over long-lived keys.

---

Reuse

• **Reusable workflow** — a whole workflow callable from others:

  # .github/workflows/drupal-tests.yml
  on:
    workflow_call:
      inputs:
        php-version: { type: string, default: '8.3' }

  # caller
  jobs:
    tests:
      uses: ./.github/workflows/drupal-tests.yml
      with:
        php-version: '8.4'

• **Composite action** — a reusable step sequence in

`.github/actions/<name>/action.yml` (e.g. "setup PHP + composer install with cache") to deduplicate job boilerplate.

---

Troubleshooting

| Symptom | Fix | |---|---| | Workflow doesn't trigger | Check `on:` filters — `branches:`/`paths:` excluded the ref, or push was from a workflow using the default token (no recursive triggers) | | `Permission denied` on push/comment from job | Widen `permissions:` for that job (e.g. `pull-requests: write`) | | Composer cache never hits | Key on `hashFiles('composer.lock')` and add a `restore-keys:` prefix fallback | | PHPUnit can't reach DB | Use `127.0.0.1` with the mapped port, not the service name (service names only resolve in container jobs) | | Deploy ran before tests finished | Add the test jobs to `needs:` of the deploy job | | Two runs per PR push | `push:` + `pull_request:` both trigger — restrict `push:` to `branches: [main]` |