managing-github-ci

saleor's avatarfrom saleor

Configures GitHub Actions workflows and CI/CD pipelines. Manages automated releases via Changesets, PR validation, and Husky hooks. Troubleshoots CI failures. Triggers on: GitHub Actions, CI pipeline, workflow, release automation, Husky hooks, gh CLI, workflow failure.

⭐20stars🔀2forks📁View on GitHub🕐Updated Dec 15, 2025⬇️2downloads

When & Why to Use This Skill

This Claude skill automates and manages GitHub CI/CD workflows, streamlining the software delivery lifecycle. It specializes in configuring GitHub Actions, managing automated package releases via Changesets, and enforcing PR validation. By providing expert troubleshooting for pipeline failures and optimizing workflow architecture, it ensures a stable, efficient, and high-quality development process.

Use Cases

  • Automating PR validation: Setting up comprehensive workflows for type checking, linting, and unit testing to ensure code quality before merging into the main branch.
  • Streamlining release management: Implementing Changesets to automate versioning, changelog generation, and publishing packages to registries like npm.
  • CI/CD troubleshooting: Analyzing failed GitHub Actions logs to identify root causes and providing specific fixes for build, test, or deployment errors.
  • Enforcing pre-push standards: Configuring Husky hooks to automate repetitive tasks, such as updating schema documentation or running local checks before code reaches the server.
  • Workflow optimization: Designing custom GitHub Actions templates that utilize caching, concurrency controls, and secret management for faster and more secure pipelines.
namemanaging-github-ci
description"Configures GitHub Actions workflows and CI/CD pipelines. Manages automated releases via Changesets, PR validation, and Husky hooks. Troubleshoots CI failures. Triggers on: GitHub Actions, CI pipeline, workflow, release automation, Husky hooks, gh CLI, workflow failure."
allowed-tools"Read, Grep, Glob, Write, Edit, Bash(gh:*)"

GitHub CI Automation

Purpose

Guide the configuration and management of GitHub Actions workflows, release automation, and CI/CD pipelines for the Saleor Configurator project.

When to Use

  • Creating or modifying GitHub Actions workflows
  • Setting up automated releases
  • Troubleshooting CI failures
  • Configuring pre-commit/pre-push hooks
  • Managing Changesets releases

Table of Contents

Project CI Architecture

.github/
├── workflows/
│   ├── test-on-pr.yml      # PR validation
│   ├── release.yml         # Automated releases
│   └── changeset-bot.yml   # Changeset automation
└── ...

.husky/
├── pre-push               # Pre-push hooks
└── ...

.changeset/
├── config.json            # Changeset configuration
└── *.md                   # Pending changesets

Workflow: test-on-pr.yml

Purpose: Validate PRs before merge

name: Test on PR

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 9

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Type check
        run: pnpm typecheck

      - name: Lint
        run: pnpm lint

      - name: Test
        run: pnpm test

      - name: Build
        run: pnpm build

Required Checks

Check Command Purpose
Type check pnpm typecheck TypeScript validation
Lint pnpm lint Biome linting
Test pnpm test Vitest test suite
Build pnpm build Compilation check

Workflow: release.yml

Purpose: Automated npm releases via Changesets

name: Release

on:
  push:
    branches: [main]

concurrency: ${{ github.workflow }}-${{ github.ref }}

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 9

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
          registry-url: 'https://registry.npmjs.org'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build
        run: pnpm build

      - name: Create Release Pull Request or Publish
        uses: changesets/action@v1
        with:
          publish: pnpm publish:ci-prod
          version: pnpm changeset version
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Release Flow

1. Developer creates changeset → pnpm changeset
2. PR merged to main
3. Changesets action runs:
   a. If changesets exist → Creates "Version Packages" PR
   b. If version PR merged → Publishes to npm

Workflow: changeset-bot.yml

Purpose: Comment on PRs about missing changesets

name: Changeset Bot

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  bot:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Changeset Bot
        uses: changesets/bot@v1
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Pre-Push Hooks (Husky)

Located in .husky/pre-push:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# Generate schema documentation before push
pnpm generate-schema-docs
git add docs/SCHEMA.md

# Check if there are changes to commit
if ! git diff --staged --quiet; then
  git commit -m "docs: update schema documentation"
fi

Hook Behavior

  • Runs generate-schema-docs before every push
  • Auto-commits schema documentation updates
  • Ensures docs stay in sync with schema changes

Changesets Configuration

Located in .changeset/config.json:

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

Changeset Types

Type When to Use
patch Bug fixes, documentation, refactoring
minor New features, non-breaking enhancements
major Breaking changes, API modifications

GitHub CLI Commands

Check Workflow Status

# List recent workflow runs
gh run list --limit 10

# View specific run
gh run view <run-id>

# Watch running workflow
gh run watch <run-id>

PR Management

# Create PR
gh pr create --title "feat: new feature" --body "Description"

# List PRs
gh pr list

# View PR details
gh pr view <pr-number>

# Check PR status
gh pr checks <pr-number>

Release Management

# List releases
gh release list

# Create release (manual)
gh release create v1.0.0 --title "v1.0.0" --notes "Release notes"

# View release
gh release view v1.0.0

Troubleshooting CI Failures

Common Failures

Type Check Fails:

# Reproduce locally
pnpm typecheck
# or
npx tsc --noEmit

Lint Fails:

# Check and auto-fix
pnpm lint
pnpm check:fix

Tests Fail:

# Run specific test
pnpm test -- --filter=<test-file>

# Run with verbose output
pnpm test -- --reporter=verbose

Build Fails:

# Reproduce locally
pnpm build

Debugging Workflow

  1. Check workflow logs in GitHub Actions UI
  2. Reproduce failure locally
  3. Fix the issue
  4. Push fix to PR
  5. Re-run failed jobs: gh run rerun <run-id>

Rate Limiting

If npm publish fails due to rate limiting:

Adding New Workflows

Template Structure

name: Workflow Name

on:
  # Trigger events
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 9

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # Add your steps here

Best Practices

  • Always use --frozen-lockfile for installs
  • Cache pnpm store for faster runs
  • Use specific action versions (@v4, not @latest)
  • Set concurrency to prevent duplicate runs
  • Use secrets for sensitive values

Secrets Management

Required Secrets

Secret Purpose Where Set
GITHUB_TOKEN Auto-provided GitHub
NPM_TOKEN npm publishing Repository Settings

Adding Secrets

  1. Go to repository Settings
  2. Navigate to Secrets and variables → Actions
  3. Click "New repository secret"
  4. Add name and value

References

Skill Reference Files

Project Resources

  • {baseDir}/.github/workflows/ - Workflow files
  • {baseDir}/.husky/ - Git hooks
  • {baseDir}/.changeset/ - Changeset configuration

External Documentation

  • Creating releases: See creating-changesets for changeset creation
  • Local validation: See validating-pre-commit for reproducing CI checks locally