managing-github-ci

name	managing-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
• Workflow: test-on-pr.yml
• Workflow: release.yml
• Workflow: changeset-bot.yml
• Pre-Push Hooks (Husky)
• Changesets Configuration
• GitHub CLI Commands
• Troubleshooting CI Failures
• Adding New Workflows
• Secrets Management
• References

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

        
          

        
          

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

             
         
        
            
             
        
             
             

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:

• Wait and retry
• Check npm status: https://status.npmjs.org/

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

• Workflow Templates - Reusable workflow patterns
• Troubleshooting Guide - Detailed debugging patterns

Project Resources

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

External Documentation

• GitHub Actions docs: https://docs.github.com/en/actions
• Changesets docs: https://github.com/changesets/changesets

Related Skills

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