playbooks

home / skills / nickcrew / claude-cortex / github-actions-workflows

github-actions-workflows skill

/skills/github-actions-workflows

This skill helps you design and optimize GitHub Actions CI/CD workflows with matrix builds, reusable patterns, caching, and secure deployment.

npx playbooks add skill nickcrew/claude-cortex --skill github-actions-workflows

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
3.3 KB
---
name: github-actions-workflows
description: GitHub Actions workflow patterns for CI/CD including matrix builds, reusable workflows, secrets management, and caching strategies. Use when setting up or optimizing GitHub Actions pipelines.
---

# GitHub Actions Workflows

Expert guidance for designing reliable, secure, and performant GitHub Actions CI/CD pipelines with patterns for matrix builds, reusable workflows, caching, and deployment automation.

## When to Use This Skill

- Setting up CI/CD pipelines with GitHub Actions from scratch
- Optimizing slow or expensive GitHub Actions workflows
- Implementing matrix builds for multi-environment testing
- Creating reusable workflows and composite actions for DRY pipelines
- Managing secrets securely across environments
- Configuring caching for dependency and build artifact reuse
- Setting up deployment workflows with staging and production gates
- Debugging failing or flaky workflow runs
- Implementing concurrency controls to prevent duplicate runs

## Quick Reference

| Task | Load reference |
| --- | --- |
| Matrix builds, reusable workflows, caching, deployment, concurrency | `skills/github-actions-workflows/references/workflow-patterns.md` |

## Core Principles

- **Structured jobs**: Break workflows into clear, distinct jobs with defined dependencies
- **DRY configuration**: Use reusable workflows and composite actions to avoid duplication
- **Security first**: Use GitHub secrets, OIDC, and minimum necessary permissions
- **Cache aggressively**: Cache dependencies, build outputs, and test fixtures
- **Trigger thoughtfully**: Configure event triggers to avoid unnecessary workflow runs
- **Document workflows**: Add comments explaining non-obvious YAML configuration

## Workflow

### 1. Design

Plan the pipeline structure before writing YAML.

- Identify trigger events (push, pull_request, schedule, workflow_dispatch)
- Map job dependencies and what can run in parallel
- Determine caching opportunities (dependencies, build outputs)
- Plan environment promotion (dev, staging, production)

### 2. Implementation

Build the pipeline incrementally.

- Start with a minimal workflow and add complexity
- Use matrix builds for multi-environment testing
- Extract reusable workflows for shared patterns
- Configure secrets management with environment protection

### 3. Optimization

Reduce runtime and cost.

- Profile workflow timing to identify bottlenecks
- Add caching for dependencies and build artifacts
- Use concurrency controls to cancel redundant runs
- Configure path filters to skip unaffected workflows

### 4. Maintenance

Keep workflows healthy over time.

- Pin action versions to specific SHAs for security
- Review and update actions regularly
- Monitor workflow runtime trends and costs
- Peer-review workflow changes before merging

## Common Mistakes

- Using `actions/checkout@main` instead of pinning to a SHA or version tag
- Not setting `permissions` block (defaults to overly broad read-write)
- Caching node_modules instead of the package manager cache directory
- Missing `concurrency` groups, leading to duplicate deploys
- Hardcoding secrets in workflow files instead of using GitHub Secrets
- Running the full test suite on every push instead of using path filters
- Not using `workflow_call` for shared CI logic across repositories

Overview

This skill provides practical GitHub Actions workflow patterns for building reliable, secure, and cost-effective CI/CD pipelines. It focuses on matrix builds, reusable workflows, secrets handling, and caching strategies to speed up pipelines and reduce duplication. The guidance is geared toward teams that need repeatable, maintainable automation for testing, building, and deploying code.

How this skill works

The skill inspects workflow design choices and recommends concrete YAML patterns: job splitting, matrix configurations, reusable workflow extraction, cache keys, and concurrency groups. It highlights security controls such as minimal permissions, OIDC, and proper secrets usage, and suggests optimizations like targeted triggers, path filters, and artifact caching. The result is a stepwise plan to implement, profile, and iterate on GitHub Actions pipelines.

When to use it

  • Setting up CI/CD pipelines with GitHub Actions from scratch
  • Optimizing slow or expensive workflows to reduce runtime and costs
  • Implementing matrix builds for multi-version or multi-platform testing
  • Creating reusable workflows or composite actions to enforce DRY pipelines
  • Securing secrets, permissions, and deployment gates across environments

Best practices

  • Design pipelines before writing YAML: define triggers, dependencies, and promotion flow
  • Start minimal, then incrementally add complexity and caching to avoid regressions
  • Pin action versions (or SHAs) and set explicit permissions blocks for least privilege
  • Cache dependency directories and build outputs with stable cache keys to speed runs
  • Use workflow_call and composite actions to centralize shared logic and simplify maintenance
  • Add path filters and concurrency groups to avoid redundant or conflicting runs

Example use cases

  • Matrix build to test a Python library across multiple versions and OS images
  • Reusable workflow for a standard build-test-release pipeline shared across repos
  • Caching pip wheels and virtualenvs to cut CI time on dependency-heavy projects
  • Deployment pipeline with staging approval, OIDC-based credentials, and production gate
  • Optimizing a monorepo by using path filters to run only affected workflows

FAQ

How do I securely use cloud credentials in workflows?

Use repository or organization secrets and prefer OIDC where supported to avoid long-lived credentials. Grant minimal permissions and use environment protection rules for production deployments.

When should I extract a reusable workflow?

Extract when multiple repositories share the same build or release steps, or when you want a single place to update CI logic to maintain consistency and reduce duplication.