workflow-setup

Table of Contents

• [When To Use](#when-to-use)
• [Standard Workflows](#standard-workflows)
• [Python Workflows](#python-workflows)
• [Rust Workflows](#rust-workflows)
• [TypeScript Workflows](#typescript-workflows)
• [Workflow](#workflow)
• [1. Check Existing Workflows](#1-check-existing-workflows)
• [2. Identify Missing Workflows](#2-identify-missing-workflows)
• [3. Render Workflow Templates](#3-render-workflow-templates)
• [4. Validate Workflows](#4-validate-workflows)
• [Workflow Best Practices](#workflow-best-practices)
• [Use Latest Action Versions](#use-latest-action-versions)
• [Matrix Testing (Python)](#matrix-testing-python)
• [Caching Dependencies](#caching-dependencies)
• [Updating Workflows](#updating-workflows)
• [Related Skills](#related-skills)

Workflow Setup Skill

Set up GitHub Actions workflows for continuous integration and deployment.

When To Use

• Need CI/CD for a new project
• Adding missing workflows to existing project
• Updating workflow versions to latest
• Automating testing and quality checks
• Setting up deployment pipelines

When NOT To Use

• GitHub Actions workflows already configured and current
• Project uses different CI platform (GitLab CI, CircleCI, etc.)
• Not hosted on GitHub
• Use /attune:upgrade-project instead for updating existing workflows

Standard Workflows

Python Workflows

1. test.yml - Run pytest on push/PR
2. lint.yml - Run ruff linting
3. typecheck.yml - Run mypy type checking
4. publish.yml - Publish to PyPI on release

Rust Workflows

1. ci.yml - Combined test/lint/check workflow
2. release.yml - Build and publish releases

TypeScript Workflows

1. test.yml - Run Jest tests
2. lint.yml - Run ESLint
3. build.yml - Build for production
4. deploy.yml - Deploy to hosting (Vercel, Netlify, etc.)

Workflow

1. Check Existing Workflows

ls -la .github/workflows/

Verification: Run the command with --help flag to verify availability.

2. Identify Missing Workflows

from project_detector import ProjectDetector

detector = ProjectDetector(Path.cwd())
language = detector.detect_language()

required_workflows = {
    "python": ["test.yml", "lint.yml", "typecheck.yml"],
    "rust": ["ci.yml"],
    "typescript": ["test.yml", "lint.yml", "build.yml"],
}

missing = detector.get_missing_configurations(language)

Verification: Run pytest -v to verify tests pass.

3. Render Workflow Templates

workflows_dir = Path(".github/workflows")
workflows_dir.mkdir(parents=True, exist_ok=True)

for workflow in required_workflows[language]:
    template = templates_dir / language / "workflows" / f"{workflow}.template"
    output = workflows_dir / workflow

    engine.render_file(template, output)
    print(f"✓ Created: {output}")

Verification: Run the command with --help flag to verify availability.

4. Validate Workflows

# Syntax check (requires act or gh CLI)
gh workflow list

# Or manually check YAML syntax
python3 -c "import yaml; yaml.safe_load(open('.github/workflows/test.yml'))"

Verification: Run pytest -v to verify tests pass.

Workflow Best Practices

Use Latest Action Versions

# Good - pinned to major version
- uses: actions/checkout@v4
- uses: actions/setup-python@v5

# Avoid - unpinned or outdated
- uses: actions/checkout@v2
- uses: actions/setup-python@latest

Verification: Run pytest -v to verify tests pass.

Matrix Testing (Python)

strategy:
  matrix:
    python-version: ["3.10", "3.11", "3.12"]
    os: [ubuntu-latest, macos-latest, windows-latest]

Verification: Run pytest -v to verify tests pass.

Caching Dependencies

- uses: actions/setup-python@v5
  with:
    python-version: '3.10'
    cache: 'pip'  # Cache pip dependencies

Verification: Run python --version to verify Python environment.

Shell Script Safety in Workflows

When writing inline shell scripts in workflows, ensure proper exit code handling:

# BAD - pipeline masks exit code
- run: |
    make typecheck 2>&1 | grep -v "^make\["
    echo "Typecheck passed"  # Runs even if make failed!

# GOOD - use pipefail
- run: |
    set -eo pipefail
    make typecheck 2>&1 | grep -v "^make\["

# GOOD - capture exit code explicitly
- run: |
    output=$(make typecheck 2>&1) || exit_code=$?
    echo "$output" | grep -v "^make\[" || true
    exit ${exit_code:-0}

For complex wrapper scripts, run /pensive:shell-review before integrating.

Updating Workflows

To update workflows to latest versions:

/attune:upgrade-project --component workflows

Verification: Run the command with --help flag to verify availability.

Related Skills

• Skill(attune:project-init) - Full project initialization
• Skill(sanctum:pr-prep) - PR preparation with CI checks

Exit Criteria

• [ ] All required workflow files for the detected language exist under .github/workflows/ (Python: test.yml + lint.yml + typecheck.yml; Rust: ci.yml; TypeScript: test.yml + lint.yml + build.yml) and contain valid YAML syntax verified by python3 -c "import yaml; yaml.safe_load(open('...'))".
• [ ] gh workflow list returns each created workflow file as an entry, confirming GitHub recognizes the workflow definitions.
• [ ] Any inline shell script in a workflow uses set -eo pipefail or explicit exit-code capture; pipeline-masked failures (cmd | grep) without pipefail are flagged as errors.
• [ ] If the project uses a CI platform other than GitHub Actions (GitLab CI, CircleCI), the skill reports this incompatibility and stops rather than generating GitHub-specific files.