Files
skills/public/collaboration-github-actions-workflows.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

812 lines
36 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>collaboration-github-actions-workflows</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/collaboration-github-actions-workflows.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/collaboration-github-actions-workflows">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/collaboration-github-actions-workflows.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>collaboration-github-actions-workflows</h1><p class="lede">Setting up CI/CD pipelines with GitHub Actions</p><h1>GitHub Actions Workflows</h1>
<p><strong>Scope</strong>: Workflow syntax, triggers, jobs, steps, matrix builds, caching, and artifacts for GitHub Actions CI/CD pipelines</p>
<p><strong>Lines</strong>: 380</p>
<p><strong>Last Updated</strong>: 2025-10-18</p>
<p><strong>Format Version</strong>: 1.0 (Atomic)</p>
<hr>
<h2>When to Use This Skill</h2>
<p>Use this skill when:</p>
<ul><li>Setting up CI/CD pipelines with GitHub Actions</li><li>Configuring workflow triggers (push, pull_request, schedule, workflow_dispatch)</li><li>Implementing matrix builds for multi-platform or multi-version testing</li><li>Optimizing workflows with caching strategies</li><li>Managing artifacts between jobs</li><li>Setting up reusable workflows and composite actions</li><li>Configuring job dependencies and conditions</li></ul>
<p>Don&#x27;t use this skill for:</p>
<ul><li>Platform-specific deployment configurations (see <code>cd-deployment-patterns.md</code>)</li><li>Testing strategies and optimization (see <code>ci-testing-strategy.md</code> and <code>ci-optimization.md</code>)</li><li>Security and secret management (see <code>ci-security.md</code>)</li></ul>
<hr>
<h2>Core Concepts</h2>
<h3>Workflow Structure</h3>
<pre><code class="lang-yaml">name: Workflow Name
on: [triggers]
env:
GLOBAL_VAR: value
jobs:
job-name:
runs-on: ubuntu-latest
steps:
- name: Step name
uses: actions/checkout@v4</code></pre>
<h3>Key Components</h3>
<ol><li><strong>Triggers (on)</strong>: Events that start workflows</li><li><strong>Jobs</strong>: Independent execution units that can run in parallel</li><li><strong>Steps</strong>: Sequential commands or actions within a job</li><li><strong>Runners</strong>: Virtual machines that execute jobs</li><li><strong>Actions</strong>: Reusable units of code (marketplace or custom)</li><li><strong>Contexts</strong>: Variables available in expressions (${{ github.event.name }})</li></ol>
<h3>Execution Model</h3>
<pre><code>Trigger Event
↓
Workflow Starts
↓
Jobs Run (Parallel by default)
↓
Each Job: Steps Execute Sequentially
↓
Workflow Completes</code></pre>
<hr>
<h2>Patterns</h2>
<h3>Basic Workflow Structure</h3>
<pre><code class="lang-yaml">name: CI Pipeline
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
env:
NODE_VERSION: &#x27;20&#x27;
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build</code></pre>
<h3>Advanced Triggers</h3>
<pre><code class="lang-yaml">on:
# Multiple events
push:
branches:
- main
- &#x27;releases/**&#x27;
paths:
- &#x27;src/**&#x27;
- &#x27;!src/docs/**&#x27;
pull_request:
types: [opened, synchronize, reopened]
# Scheduled runs (cron)
schedule:
- cron: &#x27;0 2 * * *&#x27; # Daily at 2 AM UTC
# Manual trigger with inputs
workflow_dispatch:
inputs:
environment:
description: &#x27;Deployment environment&#x27;
required: true
type: choice
options:
- staging
- production
dry_run:
description: &#x27;Run in dry-run mode&#x27;
required: false
type: boolean
default: false
# Trigger from other workflows
workflow_call:
inputs:
config-path:
required: true
type: string</code></pre>
<h3>Matrix Builds</h3>
<pre><code class="lang-yaml">jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
node: [18, 20, 22]
exclude:
# Don&#x27;t test Node 18 on Windows
- os: windows-latest
node: 18
include:
# Add experimental combinations
- os: ubuntu-latest
node: 23
experimental: true
# Continue other jobs even if one fails
fail-fast: false
# Limit concurrent jobs
max-parallel: 4
steps:
- uses: actions/checkout@v4
- name: Setup Node.js ${{ matrix.node }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
- name: Run tests
run: npm test
continue-on-error: ${{ matrix.experimental || false }}</code></pre>
<h3>Job Dependencies</h3>
<pre><code class="lang-yaml">jobs:
build:
runs-on: ubuntu-latest
steps:
- run: npm run build
test:
needs: build
runs-on: ubuntu-latest
steps:
- run: npm test
deploy-staging:
needs: [build, test]
runs-on: ubuntu-latest
steps:
- run: ./deploy.sh staging
deploy-prod:
needs: deploy-staging
if: github.ref == &#x27;refs/heads/main&#x27;
runs-on: ubuntu-latest
steps:
- run: ./deploy.sh production</code></pre>
<h3>Caching Dependencies</h3>
<pre><code class="lang-yaml">jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# Node.js with automatic caching
- uses: actions/setup-node@v4
with:
node-version: &#x27;20&#x27;
cache: &#x27;npm&#x27;
# Manual cache for custom paths
- name: Cache dependencies
uses: actions/cache@v4
with:
path: |
~/.npm
node_modules
key: ${{ runner.os }}-node-${{ hashFiles(&#x27;**/package-lock.json&#x27;) }}
restore-keys: |
${{ runner.os }}-node-
# Python with pip cache
- uses: actions/setup-python@v5
with:
python-version: &#x27;3.12&#x27;
cache: &#x27;pip&#x27;
# Rust with cargo cache
- uses: actions/cache@v4
with:
path: |
~/.cargo/bin/
~/.cargo/registry/index/
~/.cargo/registry/cache/
~/.cargo/git/db/
target/
key: ${{ runner.os }}-cargo-${{ hashFiles(&#x27;**/Cargo.lock&#x27;) }}</code></pre>
<h3>Artifacts</h3>
<pre><code class="lang-yaml">jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build artifacts
run: npm run build
# Upload artifacts
- name: Upload build artifacts
uses: actions/upload-artifact@v4
with:
name: dist-files
path: dist/
retention-days: 7
if-no-files-found: error
test:
needs: build
runs-on: ubuntu-latest
steps:
# Download artifacts
- name: Download build artifacts
uses: actions/download-artifact@v4
with:
name: dist-files
path: dist/
- name: Run integration tests
run: npm run test:integration</code></pre>
<h3>Conditional Execution</h3>
<pre><code class="lang-yaml">jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# Step-level condition
- name: Deploy to staging
if: github.ref == &#x27;refs/heads/develop&#x27;
run: ./deploy.sh staging
# Multiple conditions
- name: Deploy to production
if: |
github.ref == &#x27;refs/heads/main&#x27; &amp;&amp;
github.event_name == &#x27;push&#x27; &amp;&amp;
!contains(github.event.head_commit.message, &#x27;[skip deploy]&#x27;)
run: ./deploy.sh production
# Check previous step status
- name: Notify on failure
if: failure()
run: ./notify-slack.sh &quot;Deployment failed&quot;
# Always run (cleanup)
- name: Cleanup
if: always()
run: ./cleanup.sh</code></pre>
<h3>Reusable Workflows</h3>
<p><strong>Caller workflow:</strong></p>
<pre><code class="lang-yaml"># .github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy-prod:
uses: ./.github/workflows/reusable-deploy.yml
with:
environment: production
region: us-east-1
secrets:
api-key: ${{ secrets.PROD_API_KEY }}</code></pre>
<p><strong>Reusable workflow:</strong></p>
<pre><code class="lang-yaml"># .github/workflows/reusable-deploy.yml
name: Reusable Deploy
on:
workflow_call:
inputs:
environment:
required: true
type: string
region:
required: true
type: string
secrets:
api-key:
required: true
jobs:
deploy:
runs-on: ubuntu-latest
environment: ${{ inputs.environment }}
steps:
- uses: actions/checkout@v4
- name: Deploy to ${{ inputs.environment }}
env:
API_KEY: ${{ secrets.api-key }}
REGION: ${{ inputs.region }}
run: ./deploy.sh</code></pre>
<h3>Composite Actions</h3>
<pre><code class="lang-yaml"># .github/actions/setup-node-app/action.yml
name: &#x27;Setup Node.js Application&#x27;
description: &#x27;Checkout, setup Node.js, install dependencies&#x27;
inputs:
node-version:
description: &#x27;Node.js version&#x27;
required: false
default: &#x27;20&#x27;
runs:
using: &#x27;composite&#x27;
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
cache: &#x27;npm&#x27;
- name: Install dependencies
shell: bash
run: npm ci</code></pre>
<p><strong>Usage:</strong></p>
<pre><code class="lang-yaml">jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: ./.github/actions/setup-node-app
with:
node-version: &#x27;20&#x27;
- run: npm run build</code></pre>
<h3>Environment Variables and Contexts</h3>
<pre><code class="lang-yaml">jobs:
build:
runs-on: ubuntu-latest
env:
# Job-level environment variable
BUILD_ENV: production
steps:
- name: Print contexts
env:
# Step-level environment variable
STEP_VAR: value
run: |
echo &quot;Event: ${{ github.event_name }}&quot;
echo &quot;Ref: ${{ github.ref }}&quot;
echo &quot;SHA: ${{ github.sha }}&quot;
echo &quot;Actor: ${{ github.actor }}&quot;
echo &quot;Repository: ${{ github.repository }}&quot;
echo &quot;Run ID: ${{ github.run_id }}&quot;
echo &quot;Runner OS: ${{ runner.os }}&quot;
echo &quot;Job status: ${{ job.status }}&quot;
echo &quot;Build env: $BUILD_ENV&quot;
echo &quot;Step var: $STEP_VAR&quot;</code></pre>
<hr>
<h2>Quick Reference</h2>
<h3>Common Triggers</h3>
<pre><code class="lang-yaml">on:
push: # Code pushed
pull_request: # PR opened/updated
schedule: # Cron schedule
workflow_dispatch: # Manual trigger
release: # Release created
issue_comment: # Comment on issue/PR
workflow_call: # Called from another workflow</code></pre>
<h3>Runner Options</h3>
<pre><code class="lang-yaml">runs-on: ubuntu-latest # Linux (fastest, cheapest)
runs-on: macos-latest # macOS
runs-on: windows-latest # Windows
runs-on: [self-hosted, linux] # Self-hosted runner</code></pre>
<h3>Useful Actions</h3>
<pre><code class="lang-yaml">actions/checkout@v4 # Clone repository
actions/setup-node@v4 # Setup Node.js
actions/setup-python@v5 # Setup Python
actions/cache@v4 # Cache dependencies
actions/upload-artifact@v4 # Upload artifacts
actions/download-artifact@v4 # Download artifacts
github/codeql-action@v3 # Code scanning</code></pre>
<h3>Context Variables</h3>
<pre><code class="lang-yaml">${{ github.event_name }} # Event that triggered workflow
${{ github.ref }} # Branch or tag ref
${{ github.sha }} # Commit SHA
${{ github.actor }} # User who triggered
${{ runner.os }} # Runner OS (Linux, macOS, Windows)
${{ secrets.SECRET_NAME }} # Access secrets
${{ env.VAR_NAME }} # Environment variable</code></pre>
<h3>Status Check Functions</h3>
<pre><code class="lang-yaml">if: success() # Previous steps succeeded (default)
if: failure() # Previous step failed
if: always() # Run regardless of status
if: cancelled() # Workflow was cancelled</code></pre>
<hr>
<h2>Anti-Patterns</h2>
<h3>❌ Hardcoded Secrets</h3>
<pre><code class="lang-yaml"># WRONG: Secrets in plain text
env:
API_KEY: abc123xyz
DATABASE_URL: postgresql://user:pass@host/db</code></pre>
<pre><code class="lang-yaml"># CORRECT: Use GitHub Secrets
env:
API_KEY: ${{ secrets.API_KEY }}
DATABASE_URL: ${{ secrets.DATABASE_URL }}</code></pre>
<h3>❌ No Caching</h3>
<pre><code class="lang-yaml"># WRONG: Install dependencies every time
- run: npm install</code></pre>
<pre><code class="lang-yaml"># CORRECT: Cache dependencies
- uses: actions/setup-node@v4
with:
node-version: &#x27;20&#x27;
cache: &#x27;npm&#x27;
- run: npm ci</code></pre>
<h3>❌ Sequential Jobs (When Parallel is Possible)</h3>
<pre><code class="lang-yaml"># WRONG: Sequential tests
jobs:
test-unit:
runs-on: ubuntu-latest
steps: [...]
test-integration:
needs: test-unit
runs-on: ubuntu-latest
steps: [...]</code></pre>
<pre><code class="lang-yaml"># CORRECT: Parallel tests
jobs:
test-unit:
runs-on: ubuntu-latest
steps: [...]
test-integration:
runs-on: ubuntu-latest
steps: [...]
deploy:
needs: [test-unit, test-integration]
steps: [...]</code></pre>
<h3>❌ Using <code>npm install</code> Instead of <code>npm ci</code></h3>
<pre><code class="lang-yaml"># WRONG: Non-deterministic installs
- run: npm install</code></pre>
<pre><code class="lang-yaml"># CORRECT: Reproducible installs
- run: npm ci</code></pre>
<h3>❌ Rebuilding Artifacts</h3>
<pre><code class="lang-yaml"># WRONG: Build in multiple jobs
jobs:
test:
steps:
- run: npm run build
- run: npm test
deploy:
steps:
- run: npm run build
- run: ./deploy.sh</code></pre>
<pre><code class="lang-yaml"># CORRECT: Build once, share artifacts
jobs:
build:
steps:
- run: npm run build
- uses: actions/upload-artifact@v4
with:
name: dist
path: dist/
test:
needs: build
steps:
- uses: actions/download-artifact@v4
with:
name: dist
- run: npm test</code></pre>
<h3>❌ No Matrix for Multi-Platform</h3>
<pre><code class="lang-yaml"># WRONG: Separate jobs for each platform
jobs:
test-ubuntu:
runs-on: ubuntu-latest
steps: [...]
test-macos:
runs-on: macos-latest
steps: [...]</code></pre>
<pre><code class="lang-yaml"># CORRECT: Use matrix
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
steps: [...]</code></pre>
<hr>
<h2>Related Skills</h2>
<ul><li><code>collaboration/github/github-pull-requests.md</code> - PR workflow and code review integration with workflows</li><li><code>collaboration/github/github-security-features.md</code> - Security scanning and dependency management in Actions</li><li><code>collaboration/github/github-repository-management.md</code> - Repository settings and configuration</li><li><code>cicd/ci-testing-strategy.md</code> - Test execution patterns in CI</li><li><code>cicd/cd-deployment-patterns.md</code> - Deployment strategies and rollbacks</li><li><code>cicd/ci-optimization.md</code> - Speed and efficiency improvements</li><li><code>cicd/ci-security.md</code> - Secret management and security best practices</li></ul>
<hr>
<h2>Level 3: Resources</h2>
<h3>Overview</h3>
<p>Comprehensive resources for GitHub Actions CI/CD implementation including complete reference documentation, validation and optimization tools, and production-ready workflow examples.</p>
<h3>Resources Structure</h3>
<h4>REFERENCE.md (3,843 lines)</h4>
<p>Complete GitHub Actions reference covering:</p>
<ul><li><strong>Fundamentals</strong>: GitHub Actions architecture, workflow lifecycle, pricing/limits</li><li><strong>Workflow Syntax</strong>: Complete YAML syntax, triggers, permissions, concurrency</li><li><strong>Triggers and Events</strong>: All event types with examples (push, PR, schedule, workflow_dispatch)</li><li><strong>Jobs and Steps</strong>: Configuration, dependencies, conditions, service containers</li><li><strong>Runners</strong>: GitHub-hosted and self-hosted runners, environments</li><li><strong>Contexts and Expressions</strong>: All context objects, expression syntax, functions</li><li><strong>Actions</strong>: Using marketplace actions, creating composite actions</li><li><strong>Caching Strategies</strong>: Language-specific caching, Docker layer caching</li><li><strong>Artifacts</strong>: Upload/download patterns, release assets</li><li><strong>Matrix Builds</strong>: Multi-platform/version testing, exclusions, inclusions</li><li><strong>Reusable Workflows</strong>: Creation and usage patterns with inputs/outputs</li><li><strong>Security</strong>: OIDC authentication, permissions, secret management, pull_request_target safety</li><li><strong>Performance Optimization</strong>: Parallelization, path filters, concurrency control</li><li><strong>Monorepo Strategies</strong>: Path-based change detection, selective testing</li><li><strong>Common Patterns</strong>: Complete CI/CD pipelines, Docker builds, security scanning</li><li><strong>Anti-Patterns</strong>: Security, performance, and workflow anti-patterns with fixes</li><li><strong>Debugging</strong>: Enable debug logging, inspect contexts, troubleshoot common issues</li></ul>
<p>Location: <code>./resources/REFERENCE.md</code></p>
<h4>Scripts</h4>
<p><strong>validate_workflow.py</strong> (576 lines) Validates GitHub Actions workflow files for syntax, security, and best practices.</p>
<p>Features:</p>
<ul><li>Parse and validate YAML syntax</li><li>Detect security issues (hardcoded secrets, dangerous pull_request_target usage)</li><li>Check for outdated action versions</li><li>Identify caching opportunities</li><li>Validate permissions configuration</li><li>Suggest best practices (concurrency control, npm ci vs npm install)</li><li>JSON and human-readable output</li></ul>
<p>Usage:</p>
<pre><code class="lang-bash"># Validate single workflow
./resources/scripts/validate_workflow.py .github/workflows/ci.yml
# Validate directory with JSON output
./resources/scripts/validate_workflow.py .github/workflows/ --json
# Recursive validation with fix suggestions
./resources/scripts/validate_workflow.py . --recursive --fix-suggestions</code></pre>
<p><strong>optimize_pipeline.py</strong> (669 lines) Analyzes workflows and suggests optimizations for performance and cost.</p>
<p>Features:</p>
<ul><li>Identify parallelization opportunities</li><li>Detect duplicate builds and artifact rebuilding</li><li>Suggest caching improvements</li><li>Find matrix build opportunities</li><li>Calculate cost optimization potential</li><li>Recommend performance enhancements (path filters, shallow checkouts)</li><li>Estimate time and cost savings</li></ul>
<p>Usage:</p>
<pre><code class="lang-bash"># Analyze single workflow
./resources/scripts/optimize_pipeline.py .github/workflows/ci.yml
# JSON output with implementation details
./resources/scripts/optimize_pipeline.py workflow.yml --json --suggestions</code></pre>
<p><strong>test_actions.sh</strong> (416 lines) Tests GitHub Actions workflows locally using act (nektos/act).</p>
<p>Features:</p>
<ul><li>Run workflows locally with Docker</li><li>Test different event triggers</li><li>Measure execution time</li><li>Validate workflow outputs</li><li>List available workflows</li><li>Support for dry-run mode</li><li>JSON output for CI integration</li></ul>
<p>Usage:</p>
<pre><code class="lang-bash"># Test workflow with push event
./resources/scripts/test_actions.sh --workflow ci.yml --event push
# Test specific job
./resources/scripts/test_actions.sh --workflow ci.yml --job build
# List all workflows
./resources/scripts/test_actions.sh --list
# Dry run
./resources/scripts/test_actions.sh --workflow ci.yml --dry-run</code></pre>
<p>Dependencies:</p>
<ul><li>act: <code>brew install act</code> or <code>gh extension install nektos/gh-act</code></li><li>Docker (required by act)</li></ul>
<h4>Examples</h4>
<p><strong>workflows/python-ci.yml</strong> Complete Python CI pipeline with:</p>
<ul><li>Lint and format checking (ruff, black, isort, mypy)</li><li>Multi-version testing (Python 3.10, 3.11, 3.12)</li><li>Service containers (PostgreSQL, Redis)</li><li>Security scanning (Safety, Bandit)</li><li>Build and distribution packaging</li><li>Documentation build</li><li>Coverage reporting with Codecov</li><li>Status check job for branch protection</li></ul>
<p><strong>workflows/nodejs-ci-cd.yml</strong> Full Node.js CI/CD pipeline with:</p>
<ul><li>Multi-stage pipeline (install, lint, test, build, docker, e2e)</li><li>Multi-version testing (Node 18, 20, 22)</li><li>Docker image build and push to GHCR</li><li>E2E tests with Playwright</li><li>Deployment to staging and production environments</li><li>Artifact management and cleanup</li><li>GitHub Packages integration</li></ul>
<p><strong>workflows/monorepo-matrix.yml</strong> Monorepo CI with efficient change detection:</p>
<ul><li>Path-based change detection using dorny/paths-filter</li><li>Matrix builds for multiple packages</li><li>Conditional job execution (only run if package changed)</li><li>Integration and E2E tests for affected services</li><li>Parallel deployment of changed services</li><li>Service containers for integration tests</li></ul>
<p><strong>workflows/reusable-workflow.yml</strong> Reusable deployment workflow demonstrating:</p>
<ul><li>Workflow inputs and secrets</li><li>Environment configuration</li><li>Health checks and validation</li><li>Deployment timing and outputs</li><li>Rollback on failure</li><li>Slack notifications</li><li>Smoke tests after deployment</li></ul>
<p><strong>actions/custom-action/action.yml</strong> Composite action for multi-language setup:</p>
<ul><li>Support for Node.js, Python, Go, Rust</li><li>Automatic caching configuration</li><li>Version detection and validation</li><li>Custom install commands</li><li>Timing and performance metrics</li><li>GitHub step summary output</li></ul>
<p><strong>workflows/security-scan.yml</strong> Security scanning workflow with:</p>
<ul><li>CodeQL analysis for multiple languages</li><li>Dependency vulnerability scanning with Trivy</li><li>Secrets detection with Gitleaks</li><li>Docker image scanning</li><li>SARIF upload to GitHub Security</li><li>Scheduled weekly scans</li></ul>
<p><strong>workflows/caching-strategy.yml</strong> Advanced caching patterns for:</p>
<ul><li>Multi-layer Node.js caching (npm + node_modules + build cache)</li><li>Docker layer caching with GitHub Actions cache</li><li>Rust incremental build caching</li><li>Python pip and venv caching</li><li>Monorepo selective caching</li></ul>
<h3>Quick Start</h3>
<ol><li><strong>Validate existing workflows:</strong></li></ol>
<pre><code class="lang-bash">./resources/scripts/validate_workflow.py .github/workflows/ --recursive</code></pre>
<ol><li><strong>Optimize pipeline:</strong></li></ol>
<pre><code class="lang-bash">./resources/scripts/optimize_pipeline.py .github/workflows/ci.yml</code></pre>
<ol><li><strong>Test locally:</strong></li></ol>
<pre><code class="lang-bash">./resources/scripts/test_actions.sh --workflow ci.yml --event push</code></pre>
<ol><li><strong>Use as template:</strong></li></ol>
<p>Copy examples from <code>./resources/examples/workflows/</code> to your <code>.github/workflows/</code> directory.</p>
<ol><li><strong>Create composite action:</strong></li></ol>
<p>Copy and customize <code>./resources/examples/actions/custom-action/</code> to <code>.github/actions/</code>.</p>
<h3>Reference Links</h3>
<ul><li>Complete documentation: <a href="./resources/REFERENCE.md">REFERENCE.md</a></li><li>Official GitHub Actions docs: https://docs.github.com/en/actions</li><li>Workflow syntax: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions</li><li>Actions Marketplace: https://github.com/marketplace?type=actions</li><li>act tool: https://github.com/nektos/act</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-27</p>
<p><strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/collaboration-github-actions-workflows.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>