managing-github-ci - SKILL.md Agent Skill

name: managing-github-ci description: "Configures GitHub Actions workflows and CI/CD pipelines. Use when creating workflow YAML, managing npm releases, troubleshooting CI failures, configuring Husky hooks, or setting up release automation. Do NOT use for local development commands or application code." allowed-tools: "Read, Grep, Glob, Write, Edit, Bash(gh:*)" metadata: author: Ollie Shop version: 1.0.0 compatibility: "Claude Code with Node.js >=20, pnpm, TypeScript 5.5+"

GitHub CI Automation

Overview

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 via Changesets
Troubleshooting CI failures
Configuring pre-commit/pre-push hooks (Husky)

Quick Reference

Workflow	Trigger	Purpose
`test-on-pr.yml`	PR to main	Typecheck, lint, test, build
`release.yml`	Push to main	Changesets publish to npm
`changeset-bot.yml`	PR opened/synced	Comment on missing changesets

Project CI Architecture

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

.husky/
├── pre-push               # Schema docs generation

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

Workflows

test-on-pr.yml

Validates PRs before merge. Runs: typecheck, lint, test, build. Uses pnpm 9 + Node 20.

See references/workflow-templates.md for full YAML.

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

release.yml

Automated npm releases via Changesets. Triggers on push to main with concurrency control.

Uses changesets/action@v1 with pnpm publish:ci-prod. Requires GITHUB_TOKEN and 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

changeset-bot.yml

Comments on PRs about missing changesets. Uses changesets/bot@v1.

Pre-Push Hooks (Husky)

Located in .husky/pre-push:

Runs pnpm 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. Key settings: access: "public", baseBranch: "main".

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

GitHub CLI

Use gh for workflow management: gh run list, gh run view <id>, gh run watch <id>, gh run rerun <id>, gh pr checks <number>.

Troubleshooting CI Failures

Reproduce Locally

Failure	Command
Type check	`pnpm typecheck` or `npx tsc --noEmit`
Lint	`pnpm lint` then `pnpm check:fix`
Tests	`pnpm test -- --filter=<file>`
Build	`pnpm build`

Debugging Steps

Check workflow logs in GitHub Actions UI
Reproduce failure locally with commands above
Fix the issue
Push fix to PR
Re-run failed jobs: gh run rerun <run-id>

npm Publish Rate Limiting

If npm publish fails: wait and retry. Check status at https://status.npmjs.org/

Secrets Management

Secret	Purpose	Where Set
`GITHUB_TOKEN`	Auto-provided	GitHub
`NPM_TOKEN`	npm publishing	Repository Settings > Secrets > Actions

Common Mistakes

Mistake	Fix
Missing `--frozen-lockfile`	Always use in CI installs
Using `@latest` action versions	Pin to specific versions (`@v4`)
No `concurrency` setting	Add to prevent duplicate runs
Forgetting to add changeset	Run `pnpm changeset` before PR

References

Skill Reference Files

Workflow Templates - Full YAML workflow definitions and reusable patterns
Troubleshooting Guide - Detailed debugging patterns

Project Resources

.github/workflows/ - Workflow files
.husky/ - Git hooks
.changeset/ - Changeset configuration

Related Skills

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