managing-github-ci

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

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

• [Project CI Architecture](#project-ci-architecture)
• [Workflow: test-on-pr.yml](#workflow-test-on-pryml)
• [Workflow: release.yml](#workflow-releaseyml)
• [Workflow: changeset-bot.yml](#workflow-changeset-botyml)
• [Pre-Push Hooks (Husky)](#pre-push-hooks-husky)
• [Changesets Configuration](#changesets-configuration)
• [GitHub CLI Commands](#github-cli-commands)
• [Troubleshooting CI Failures](#troubleshooting-ci-failures)
• [Adding New Workflows](#adding-new-workflows)
• [Secrets Management](#secrets-management)
• [References](#references)

```

.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

```

Purpose: Validate PRs before merge

```yaml

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 |

Purpose: Automated npm releases via Changesets

```yaml

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

```

Purpose: Comment on PRs about missing changesets

```yaml

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 }}

```

Located in .husky/pre-push:

```bash

#!/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

Located in .changeset/config.json:

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

Check Workflow Status

```bash

# List recent workflow runs

gh run list --limit 10

# View specific run

gh run view

# Watch running workflow

gh run watch

```

PR Management

```bash

# Create PR

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

# List PRs

gh pr list

# View PR details

gh pr view

# Check PR status

gh pr checks

```

Release Management

```bash

# 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

```

Common Failures

Type Check Fails:

```bash

# Reproduce locally

pnpm typecheck

# or

npx tsc --noEmit

```

Lint Fails:

```bash

# Check and auto-fix

pnpm lint

pnpm check:fix

```

Tests Fail:

```bash

# Run specific test

pnpm test -- --filter=

# Run with verbose output

pnpm test -- --reporter=verbose

```

Build Fails:

```bash

# 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

Rate Limiting

If npm publish fails due to rate limiting:

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

Template Structure

```yaml

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

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

Skill Reference Files

• [Workflow Templates](references/workflow-templates.md) - Reusable workflow patterns
• [Troubleshooting Guide](references/troubleshooting.md) - 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

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