mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
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]>
812 lines
36 KiB
HTML
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'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: '20'
|
|
|
|
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
|
|
- 'releases/**'
|
|
paths:
|
|
- 'src/**'
|
|
- '!src/docs/**'
|
|
|
|
pull_request:
|
|
types: [opened, synchronize, reopened]
|
|
|
|
# Scheduled runs (cron)
|
|
schedule:
|
|
- cron: '0 2 * * *' # Daily at 2 AM UTC
|
|
|
|
# Manual trigger with inputs
|
|
workflow_dispatch:
|
|
inputs:
|
|
environment:
|
|
description: 'Deployment environment'
|
|
required: true
|
|
type: choice
|
|
options:
|
|
- staging
|
|
- production
|
|
dry_run:
|
|
description: 'Run in dry-run mode'
|
|
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'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 == 'refs/heads/main'
|
|
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: '20'
|
|
cache: 'npm'
|
|
|
|
# Manual cache for custom paths
|
|
- name: Cache dependencies
|
|
uses: actions/cache@v4
|
|
with:
|
|
path: |
|
|
~/.npm
|
|
node_modules
|
|
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
|
|
restore-keys: |
|
|
${{ runner.os }}-node-
|
|
|
|
# Python with pip cache
|
|
- uses: actions/setup-python@v5
|
|
with:
|
|
python-version: '3.12'
|
|
cache: 'pip'
|
|
|
|
# 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('**/Cargo.lock') }}</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 == 'refs/heads/develop'
|
|
run: ./deploy.sh staging
|
|
|
|
# Multiple conditions
|
|
- name: Deploy to production
|
|
if: |
|
|
github.ref == 'refs/heads/main' &&
|
|
github.event_name == 'push' &&
|
|
!contains(github.event.head_commit.message, '[skip deploy]')
|
|
run: ./deploy.sh production
|
|
|
|
# Check previous step status
|
|
- name: Notify on failure
|
|
if: failure()
|
|
run: ./notify-slack.sh "Deployment failed"
|
|
|
|
# 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: 'Setup Node.js Application'
|
|
description: 'Checkout, setup Node.js, install dependencies'
|
|
|
|
inputs:
|
|
node-version:
|
|
description: 'Node.js version'
|
|
required: false
|
|
default: '20'
|
|
|
|
runs:
|
|
using: 'composite'
|
|
steps:
|
|
- name: Checkout code
|
|
uses: actions/checkout@v4
|
|
|
|
- name: Setup Node.js
|
|
uses: actions/setup-node@v4
|
|
with:
|
|
node-version: ${{ inputs.node-version }}
|
|
cache: 'npm'
|
|
|
|
- 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: '20'
|
|
|
|
- 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 "Event: ${{ github.event_name }}"
|
|
echo "Ref: ${{ github.ref }}"
|
|
echo "SHA: ${{ github.sha }}"
|
|
echo "Actor: ${{ github.actor }}"
|
|
echo "Repository: ${{ github.repository }}"
|
|
echo "Run ID: ${{ github.run_id }}"
|
|
echo "Runner OS: ${{ runner.os }}"
|
|
echo "Job status: ${{ job.status }}"
|
|
echo "Build env: $BUILD_ENV"
|
|
echo "Step var: $STEP_VAR"</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: '20'
|
|
cache: 'npm'
|
|
- 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> |