Github Actions

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