# github-actions

Adopt this skill: https://proskills.md/skills/other/siva01c-claude-plugins-cicd-tools-skills-github-actions

Page: https://proskills.md/skills/other/siva01c-claude-plugins-cicd-tools-skills-github-actions
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: cicd-tools/skills/github-actions/SKILL.md
size: 6785
sha: 88e7755febb2d275646049f4f71efd7e27a539f9
upstream: https://github.com/siva01c/claude-plugins/blob/main/cicd-tools/skills/github-actions/SKILL.md

````text
---
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

```yaml
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

```yaml
  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

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

---

## Semgrep SAST with SARIF

Semgrep runs in its own container image, so no PHP or Composer setup is
needed. SARIF uploaded to code scanning shows each finding on the PR diff and
under Security → Code scanning (public repos, or private ones with GitHub
Advanced Security).

```yaml
  semgrep:
    runs-on: ubuntu-latest
    container: semgrep/semgrep
    permissions:
      contents: read
      security-events: write   # upload-sarif needs it; keep it on this job only
    steps:
      - uses: actions/checkout@v4
      - run: >-
          semgrep scan --metrics=off --sarif --output semgrep.sarif
          --config p/php --config p/owasp-top-ten --config p/secrets
          --config .semgrep/drupal.yml --config .semgrep/drupal-routing.yml
          web/modules/custom web/themes/custom
      - uses: github/codeql-action/upload-sarif@v3
        if: always()            # upload even when the scan step failed on findings
        with:
          sarif_file: semgrep.sarif
          category: semgrep
```

- Copy the custom Drupal rules (the `security-tools` `semgrep` skill's
  `rules/drupal.yml` and `rules/drupal-routing.yml`) into the project, here
  `.semgrep/`, so CI does not depend on a local plugin path.
- Add `--error` to fail the job on any finding; without it the job stays green
  and code scanning carries the findings.
- Fork PRs get a read-only token, so the upload step fails there — guard it
  with `if: github.event.pull_request.head.repo.full_name == github.repository`
  when the project takes outside contributions.

---

## Deployment job

```yaml
  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:

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

  ```yaml
  # 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]` |
````

## File: README.md
upstream: https://github.com/siva01c/claude-plugins/blob/main/README.md

````text
# Claude Code Plugin Marketplace

A curated collection of [Claude Code](https://claude.com/claude-code) plugins for **Drupal development, security, and deployment**. Each plugin covers one topic — Drupal itself, DDEV, Docker, CI/CD, git workflows, and security verification — so you install only what you need.

## Repository

[https://github.com/siva01c/claude-plugins](https://github.com/siva01c/claude-plugins)

## Available Plugins

| Plugin | Version | Contents |
|---|---|---|
| [drupal-dev-tools](drupal-dev-tools/) | 4.1.0 | `/drupal-dev-tools:drupal` audit command, skills: module development, security review |
| [ddev-tools](ddev-tools/) | 1.0.0 | `drupal-ddev` agent, skill: DDEV operations for Drupal projects |
| [git-tools](git-tools/) | 1.0.0 | Skill: git worktrees for parallel, conflict-free work |
| [security-tools](security-tools/) | 1.1.1 | Skills: OWASP ASVS v5.0 checklist mapped to Drupal 11 APIs, Semgrep SAST with custom Drupal rules |
| [docker-tools](docker-tools/) | 1.0.0 | Skills: Docker Compose for Drupal stacks, Docker Model Runner for local AI models |
| [cicd-tools](cicd-tools/) | 1.1.0 | Skills: GitLab CI and GitHub Actions pipelines for Drupal projects |
| [workflow-tools](workflow-tools/) | 1.1.0 | Skills: phased feature/deploy workflows and a tiny-fix path, rigor scaled to risk |
| [quality-tools](quality-tools/) | 1.0.0 | Skills: SOLID and DRY design review rules |

### drupal-dev-tools

Comprehensive Drupal 11 toolkit:

- **Slash command `/drupal-dev-tools:drupal`** — full code audit of custom themes and modules: Drupal 11 standards, security (SQL injection, XSS, unsafe input), SOLID/DRY design review, duplication, refactoring recommendations. Starts the security section from a Semgrep scan when `security-tools` is installed and Semgrep can run.
- **Skills** — `drupal-module-development`, `drupal-security-review`.

### ddev-tools

DDEV is a multiplatform local development environment (built on Docker), so it has its own plugin:

- **Agent `drupal-ddev`** — manages DDEV-based Drupal 11 projects: modules, configuration, database operations, caches, Composer workflows.
- **`drupal-ddev-operations`** — safe operational workflows for Drupal in DDEV: backup-first updates, database/config import-export, troubleshooting.

### git-tools

- **`git-worktree`** — check out multiple branches into separate directories so parallel tasks (or parallel Claude sessions) never conflict. Covers create/list/remove/move/repair, agent workflow, and safety rules.

### security-tools

- **`owasp-asvs`** — OWASP ASVS v5.0 verification checklist (V1–V14) with every requirement mapped to Drupal 11 APIs (`Xss::filter()`, Query Builder, Flood control, Key module…), critical security patterns in PHP, red-flags table, and recommended Drupal security modules.
- **`semgrep`** — Semgrep as the deterministic SAST layer under a security review: runs through a local `semgrep` or `docker run semgrep/semgrep` (no global install) with `p/php`, `p/owasp-top-ten`, `p/secrets` and custom Drupal rules (SQL injection in `query()`/`db_query()`, XSS through `#markup` and `Markup::create()`, superglobals, `\Drupal::` in DI classes, debug leftovers, routes without access checks). Every custom rule maps to an ASVS requirement and has a `ruleid:`/`ok:` fixture for `semgrep --test`; every finding is reported with rule id, `file:line`, ASVS and a triage verdict.

### docker-tools

- **`docker-compose`** — compose.yaml authoring and operations with a Drupal stack (php-fpm, nginx, MariaDB, Redis) as the working example: healthchecks, depends_on conditions, dev/prod override files, profiles, troubleshooting.
- **`docker-model`** — Docker Model Runner: pull/run local AI models, OpenAI-compatible endpoints, the Compose `models:` element, and using it as a local backend for the Drupal AI module.

### cicd-tools

- **`gitlab-ci`** — `.gitlab-ci.yml` authoring for Drupal: composer caching, phpcs/phpstan/phpunit jobs with a MariaDB service, `rules:`, environments, and drush-based deployment.
- **`github-actions`** — workflows for Drupal: least-privilege permissions, concurrency, matrix PHP builds, database services, reusable workflows, and SSH/drush deployment.
- Both include a Semgrep SAST job with SARIF output (code scanning upload on GitHub, SARIF artifact plus the MR security widget on GitLab).

### workflow-tools

Phased development workflows that orchestrate the other plugins' skills, with rigor scaled to the risk of the task:

- **`feature-workflow`** — gated plan → implement → review → test → finalize procedure for non-trivial Drupal changes. Classifies the task first (standard / security-sensitive / schema-touching) and adds a mandatory security pass or update-hook requirement accordingly. Uses `drupal-module-development`, the `/drupal-dev-tools:drupal` audit, an optional `semgrep` scan in Phase 3, and `owasp-asvs` when those plugins are installed, with documented manual fallbacks when they are not.
- **`deploy-workflow`** — safe deployment sequence: pre-flight config-status check, mandatory backup, `composer install` → `drush updb` → `drush cim` → `drush cr` (or `drush deploy`), post-deploy verification, and a rollback plan. Covers per-site update passes for multisite releases.
- **`tiny-fix`** — deliberately minimal path for typos, CSS tweaks, and single-line changes, with an escalation tripwire to `feature-workflow` the moment a change touches logic, config, security, or schema.

### quality-tools

Design review rules that pair with `security-tools:owasp-asvs` in a code review:

- **`solid`** — SRP, OCP, LSP, ISP and DIP as review rules: what counts as a finding (a real cost today or on the next change), what is only taste, severity scale and what each finding must cite.
- **`dry`** — duplicated *knowledge* (rules, constants, parsers, protocol details) rather than similar-looking text: what to look for, what is not a finding, severity by whether the copies have already drifted.

## Installation

### Step 1: Add the Marketplace

In Claude Code, run the following command to add this plugin marketplace:

```
/plugin marketplace add siva01c/claude-plugins
```

### Step 2: List Available Plugins

View all plugins available in the marketplace:

```
/plugin marketplace list
```

### Step 3: Install Plugins

Install any plugin with `/plugin install <plugin-name>@<marketplace-name>`:

```
/plugin install drupal-dev-tools@dev-tools
/plugin install ddev-tools@dev-tools
/plugin install git-tools@dev-tools
/plugin install security-tools@dev-tools
/plugin install docker-tools@dev-tools
/plugin install cicd-tools@dev-tools
/plugin install workflow-tools@dev-tools
/plugin install quality-tools@dev-tools
```

### Step 4: Verify Installation

Check that the plugins are installed:

```
/plugin list
```

## Updating Plugins

Pushing new commits to this repository does **not** automatically update an already-installed plugin. Claude Code keeps a local cache of both the marketplace catalog and the installed plugin (pinned to a specific git commit), so you have to refresh them manually.

### Step 1: Refresh the Marketplace Catalog

Fetch the latest catalog from this repository:

```
/plugin marketplace update dev-tools
```

The format is: `/plugin marketplace update <marketplace-name>`. Use `--all` to refresh every marketplace at once.

### Step 2: Update the Installed Plugin

Refreshing the catalog does not change the installed copy on its own. Reinstall the plugin to pull the latest version:

```
/plugin uninstall drupal-dev-tools@dev-tools
/plugin install drupal-dev-tools@dev-tools
```

### Step 3: Reload Plugins

Activate the changes in your current session (or restart Claude Code):

```
/reload-plugins
```

### Optional: Enable Auto-Update

To have the marketplace pull the latest version automatically on startup:

1. Run `/plugin`
2. Open the **Marketplaces** tab
3. Select your marketplace
4. Toggle **Enable auto-update**

### Tip: Local Development

If you are developing this plugin locall
````
