agentic-awesome-skills 工作流自动化技能实战:CI/CD 流水线、发布、基础设施与安全自动化的完整实施指南
agentic-awesome-skills 工作流自动化技能实战:CI/CD 流水线、发布、基础设施与安全自动化的完整实施指南
本篇技术指南以 AAS(agentic-awesome-skills)仓库中的 cicd-automation-workflow-automate 技能为骨架,系统讲解如何用 Agent 驱动的方式设计并落地高效的 CI/CD 流水线、GitHub Actions 工作流与自动化开发流程。读者将掌握从工作流盘点、多环境流水线设计、语义化发布、pre-commit 钩子到 Terraform 基础设施编排、监控告警、依赖更新、文档与安全扫描自动化的全套可复制方案,并理解这些模式在 AAS 仓库自身 CI 中的真实落地方式。
一、技能定位:何时使用、何时禁用与安全边界
cicd-automation-workflow-automate 是 AAS 仓库中的一个 Agent 技能(Skill),其能力声明定义在 SKILL.md 中:它把使用它的 Agent 塑造成一位工作流自动化专家,专注于创建高效的 CI/CD 流水线、GitHub Actions 工作流与自动化开发流程,通过自动化减少人工操作、提升一致性、加速交付,同时保持质量与安全。该技能在 data/catalog.json 中被归类为 automation 类别、risk: critical 高风险等级,社区来源,内置触发词 cicd、automate、automation、github、actions 等,便于 Agent 在检索时自动命中。
1.1 使用条件(Use this skill when)
- 自动化 CI/CD 工作流或发布流水线;
- 设计 GitHub Actions 或多阶段构建/测试/部署流程;
- 用自动化替代手动的构建、测试或部署步骤;
- 提升流水线的可靠性、可见性或合规检查能力。
1.2 禁用条件(Do not use this skill when)
- 只需要一次性的命令或快速排障;
- 不存在工作流或自动化上下文;
- 任务纯粹属于产品设计或 UI 设计范畴。
1.3 安全边界(Safety)
- 未经审批与回滚预案,不要执行部署步骤;
- 将密钥(Secrets)与环境配置变更视为高风险操作。
1.4 输入与输出约定
技能的 Requirements 通过 $ARGUMENTS 注入用户需求;输出格式固定为四部分:流水线阶段与触发器摘要、建议的工作流文件或步骤清单、所需的 secrets / 环境变量 / 服务集成、风险、假设与回滚说明。技能还明确要求:当需要更细致的工作流模式时,打开 resources/implementation-playbook.md——即本文第二节起的全部内容来源。
二、工作流分析:盘点现状、识别自动化机会
任何自动化改造的第一步都不是写 YAML,而是先盘点现状。实施手册给出了一个可复用的 WorkflowAnalyzer 分析器(implementation-playbook.md 第 1 节):
import os
import yaml
import json
from pathlib import Path
from typing import List, Dict, Any
class WorkflowAnalyzer:
def analyze_project(self, project_path: str) -> Dict[str, Any]:
"""
Analyze project to identify automation opportunities
"""
analysis = {
'current_workflows': self._find_existing_workflows(project_path),
'manual_processes': self._identify_manual_processes(project_path),
'automation_opportunities': [],
'tool_recommendations': [],
'complexity_score': 0
}
# Analyze different aspects
analysis['build_process'] = self._analyze_build_process(project_path)
analysis['test_process'] = self._analyze_test_process(project_path)
analysis['deployment_process'] = self._analyze_deployment_process(project_path)
analysis['code_quality'] = self._analyze_code_quality_checks(project_path)
# Generate recommendations
self._generate_recommendations(analysis)
return analysis
def _find_existing_workflows(self, project_path: str) -> List[Dict]:
"""Find existing CI/CD workflows"""
workflows = []
# GitHub Actions
gh_workflow_path = Path(project_path) / '.github' / 'workflows'
if gh_workflow_path.exists():
for workflow_file in gh_workflow_path.glob('*.y*ml'):
with open(workflow_file) as f:
workflow = yaml.safe_load(f)
workflows.append({
'type': 'github_actions',
'name': workflow.get('name', workflow_file.stem),
'file': str(workflow_file),
'triggers': list(workflow.get('on', {}).keys())
})
# GitLab CI
gitlab_ci = Path(project_path) / '.gitlab-ci.yml'
if gitlab_ci.exists():
with open(gitlab_ci) as f:
config = yaml.safe_load(f)
workflows.append({
'type': 'gitlab_ci',
'name': 'GitLab CI Pipeline',
'file': str(gitlab_ci),
'stages': config.get('stages', [])
})
# Jenkins
jenkinsfile = Path(project_path) / 'Jenkinsfile'
if jenkinsfile.exists():
workflows.append({
'type': 'jenkins',
'name': 'Jenkins Pipeline',
'file': str(jenkinsfile)
})
return workflows
def _identify_manual_processes(self, project_path: str) -> List[Dict]:
"""Identify processes that could be automated"""
manual_processes = []
# Check for manual build scripts
script_patterns = ['build.sh', 'deploy.sh', 'release.sh', 'test.sh']
for pattern in script_patterns:
scripts = Path(project_path).glob(f'**/{pattern}')
for script in scripts:
manual_processes.append({
'type': 'script',
'file': str(script),
'purpose': pattern.replace('.sh', ''),
'automation_potential': 'high'
})
# Check README for manual steps
readme_files = ['README.md', 'README.rst', 'README.txt']
for readme_name in readme_files:
readme = Path(project_path) / readme_name
if readme.exists():
content = readme.read_text()
if any(keyword in content.lower() for keyword in ['manually', 'by hand', 'steps to']):
manual_processes.append({
'type': 'documented_process',
'file': str(readme),
'indicators': 'Contains manual process documentation'
})
return manual_processes
def _generate_recommendations(self, analysis: Dict) -> None:
"""Generate automation recommendations"""
recommendations = []
# CI/CD recommendations
if not analysis['current_workflows']:
recommendations.append({
'priority': 'high',
'category': 'ci_cd',
'recommendation': 'Implement CI/CD pipeline',
'tools': ['GitHub Actions', 'GitLab CI', 'Jenkins'],
'effort': 'medium'
})
# Build automation
if analysis['build_process']['manual_steps']:
recommendations.append({
'priority': 'high',
'category': 'build',
'recommendation': 'Automate build process',
'tools': ['Make', 'Gradle', 'npm scripts'],
'effort': 'low'
})
# Test automation
if not analysis['test_process']['automated_tests']:
recommendations.append({
'priority': 'high',
'category': 'testing',
'recommendation': 'Implement automated testing',
'tools': ['Jest', 'Pytest', 'JUnit'],
'effort': 'medium'
})
# Deployment automation
if analysis['deployment_process']['manual_deployment']:
recommendations.append({
'priority': 'critical',
'category': 'deployment',
'recommendation': 'Automate deployment process',
'tools': ['ArgoCD', 'Flux', 'Terraform'],
'effort': 'high'
})
analysis['automation_opportunities'] = recommendations
关键设计点解读:
_find_existing_workflows同时识别三种主流 CI 载体(GitHub Actions 的.github/workflows/*.yml、GitLab CI 的.gitlab-ci.yml、Jenkins 的Jenkinsfile),避免重复建设;_identify_manual_processes通过扫描build.sh/deploy.sh/release.sh/test.sh及 README 中的manually、by hand、steps to等关键词,定位“还靠人肉执行”的环节;_generate_recommendations按优先级输出建议:无 CI 时先建 CI/CD(effort=medium),手动构建用 Make/Gradle/npm scripts 自动化(effort=low),缺自动化测试则引入 Jest/Pytest/JUnit,手动部署是critical优先级并推荐 ArgoCD/Flux/Terraform(effort=high)。
三、GitHub Actions 多环境 CI/CD 流水线
实施手册第 2 节给出了一个覆盖“质量检查 → 测试 → 构建 → 部署 → 验证”五个阶段的多环境流水线,可直接作为 .github/workflows/ci-cd.yml 使用:
# .github/workflows/ci-cd.yml
name: CI/CD Pipeline
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
release:
types: [created]
env:
NODE_VERSION: '18'
PYTHON_VERSION: '3.11'
GO_VERSION: '1.21'
jobs:
# Code quality checks
quality:
name: Code Quality
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Full history for better analysis
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
cache: 'npm'
- name: Cache dependencies
uses: actions/cache@v3
with:
path: |
~/.npm
~/.cache
node_modules
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
- name: Install dependencies
run: npm ci
- name: Run linting
run: |
npm run lint
npm run lint:styles
- name: Type checking
run: npm run typecheck
- name: Security audit
run: |
npm audit --production
npx snyk test
- name: License check
run: npx license-checker --production --onlyAllow 'MIT;Apache-2.0;BSD-3-Clause;BSD-2-Clause;ISC'
# Testing
test:
name: Test Suite
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
node: [16, 18, 20]
steps:
- uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run unit tests
run: npm run test:unit -- --coverage
- name: Run integration tests
run: npm run test:integration
env:
TEST_DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }}
- name: Upload coverage
if: matrix.os == 'ubuntu-latest' && matrix.node == 18
uses: codecov/codecov-action@v3
with:
token: ${{ secrets.CODECOV_TOKEN }}
flags: unittests
name: codecov-umbrella
# Build
build:
name: Build Application
needs: [quality, test]
runs-on: ubuntu-latest
strategy:
matrix:
environment: [development, staging, production]
steps:
- uses: actions/checkout@v4
- name: Set up build environment
uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build application
run: npm run build
env:
NODE_ENV: ${{ matrix.environment }}
BUILD_NUMBER: ${{ github.run_number }}
COMMIT_SHA: ${{ github.sha }}
- name: Build Docker image
run: |
docker build \
--build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
--build-arg VCS_REF=${GITHUB_SHA::8} \
--build-arg VERSION=${GITHUB_REF#refs/tags/} \
-t ${{ github.repository }}:${{ matrix.environment }}-${{ github.sha }} \
-t ${{ github.repository }}:${{ matrix.environment }}-latest \
.
- name: Scan Docker image
uses: aquasecurity/trivy-action@master
with:
image-ref: ${{ github.repository }}:${{ matrix.environment }}-${{ github.sha }}
format: 'sarif'
output: 'trivy-results.sarif'
- name: Upload scan results
uses: github/codeql-action/upload-sarif@v2
with:
sarif_file: 'trivy-results.sarif'
- name: Push to registry
if: github.event_name != 'pull_request'
run: |
echo ${{ secrets.DOCKER_PASSWORD }} | docker login -u ${{ secrets.DOCKER_USERNAME }} --password-stdin
docker push ${{ github.repository }}:${{ matrix.environment }}-${{ github.sha }}
docker push ${{ github.repository }}:${{ matrix.environment }}-latest
- name: Upload artifacts
uses: actions/upload-artifact@v3
with:
name: build-${{ matrix.environment }}
path: |
dist/
build/
.next/
retention-days: 7
# Deploy
deploy:
name: Deploy to ${{ matrix.environment }}
needs: build
runs-on: ubuntu-latest
if: github.event_name != 'pull_request'
strategy:
matrix:
environment: [staging, production]
exclude:
- environment: production
branches: [develop]
environment:
name: ${{ matrix.environment }}
url: ${{ steps.deploy.outputs.url }}
steps:
- uses: actions/checkout@v4
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v2
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region: us-east-1
- name: Deploy to ECS
id: deploy
run: |
# Update task definition
aws ecs register-task-definition \
--family myapp-${{ matrix.environment }} \
--container-definitions "[{
\"name\": \"app\",
\"image\": \"${{ github.repository }}:${{ matrix.environment }}-${{ github.sha }}\",
\"environment\": [{
\"name\": \"ENVIRONMENT\",
\"value\": \"${{ matrix.environment }}\"
}]
}]"
# Update service
aws ecs update-service \
--cluster ${{ matrix.environment }}-cluster \
--service myapp-service \
--task-definition myapp-${{ matrix.environment }}
# Get service URL
echo "url=https://${{ matrix.environment }}.example.com" >> $GITHUB_OUTPUT
- name: Notify deployment
uses: 8398a7/action-slack@v3
with:
status: ${{ job.status }}
text: Deployment to ${{ matrix.environment }} ${{ job.status }}
webhook_url: ${{ secrets.SLACK_WEBHOOK }}
if: always()
# Post-deployment verification
verify:
name: Verify Deployment
needs: deploy
runs-on: ubuntu-latest
strategy:
matrix:
environment: [staging, production]
steps:
- uses: actions/checkout@v4
- name: Run smoke tests
run: |
npm run test:smoke -- --url https://${{ matrix.environment }}.example.com
- name: Run E2E tests
uses: cypress-io/github-action@v5
with:
config: baseUrl=https://${{ matrix.environment }}.example.com
record: true
env:
CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
- name: Performance test
run: |
npm install -g @sitespeed.io/sitespeed.io
sitespeed.io https://${{ matrix.environment }}.example.com \
--budget.configPath=.sitespeed.io/budget.json \
--plugins.add=@sitespeed.io/plugin-lighthouse
- name: Security scan
run: |
npm install -g @zaproxy/action-baseline
zaproxy/action-baseline -t https://${{ matrix.environment }}.example.com
这套流水线的工程要点:
- 依赖编排:
build通过needs: [quality, test]显式声明依赖,deploy依赖build,verify依赖deploy,形成串行门禁(quality gate),任何上游失败都会阻断下游,杜绝“带着坏代码进生产”; - 缓存策略:
actions/cache以package-lock.json的哈希作为key,配合restore-keys前缀回退,显著缩短npm ci的安装时间; - 矩阵与排除规则:测试阶段用
os × node矩阵覆盖三操作系统三 Node 版本;部署阶段用exclude排除production + develop组合,保证 develop 分支只能进入 staging; - 环境保护:
environment:块绑定环境名称与部署 URL,可配合仓库级环境保护规则实现人工审批门; - 制品可追溯:Docker 镜像同时打
$sha与-latest双标签,构建参数注入BUILD_DATE、VCS_REF、VERSION,满足供应链可追溯要求; - 发布后验证闭环:smoke 测试、Cypress E2E、sitespeed.io 性能预算、ZAP 基线安全扫描全部落在
verify阶段,验证不通过则部署结果视为失败。
四、发布自动化:语义化版本与自动生成 Changelog
第 3 节讲解 release 自动化。核心是 Semantic Release 工作流(.github/workflows/release.yml):
# .github/workflows/release.yml
name: Release
on:
push:
branches:
- main
jobs:
release:
name: Create Release
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
persist-credentials: false
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 18
- name: Install dependencies
run: npm ci
- name: Run semantic release
env:
GITHUB_TOKEN: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
run: npx semantic-release
- name: Update documentation
if: steps.semantic-release.outputs.new_release_published == 'true'
run: |
npm run docs:generate
npm run docs:publish
- name: Create release notes
if: steps.semantic-release.outputs.new_release_published == 'true'
uses: actions/github-script@v6
with:
script: |
const { data: releases } = await github.rest.repos.listReleases({
owner: context.repo.owner,
repo: context.repo.repo,
per_page: 1
});
const latestRelease = releases[0];
const changelog = await generateChangelog(latestRelease);
// Update release notes
await github.rest.repos.updateRelease({
owner: context.repo.owner,
repo: context.repo.repo,
release_id: latestRelease.id,
body: changelog
});
配套的发布配置 .releaserc.js:
// .releaserc.js
module.exports = {
branches: [
'main',
{ name: 'beta', prerelease: true },
{ name: 'alpha', prerelease: true }
],
plugins: [
'@semantic-release/commit-analyzer',
'@semantic-release/release-notes-generator',
['@semantic-release/changelog', {
changelogFile: 'CHANGELOG.md'
}],
'@semantic-release/npm',
['@semantic-release/git', {
assets: ['CHANGELOG.md', 'package.json'],
message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}'
}],
'@semantic-release/github'
]
};
要点解析:
branches中main为正式发布通道,beta/alpha为预发布通道,通过prerelease: true区分,实现“主干稳定、预发通道先行”的发布节奏;- 插件链完整覆盖版本分析(commit-analyzer)、更新日志生成(changelog 写入
CHANGELOG.md)、npm 发布、git 提交回写(携带[skip ci]防止循环触发)与 GitHub Release 创建; persist-credentials: false配合专用SEMANTIC_RELEASE_TOKEN,避免默认 token 权限过大或触发无限工作流循环;- 使用
github-script在发布后读取最新 Release 并回写补充生成式 Changelog,同时可联动docs:generate/docs:publish更新文档站点。
五、开发工作流自动化:pre-commit 钩子与一键开发环境
第 4 节覆盖开发侧的自动化,先用 .pre-commit-config.yaml 把所有静态检查前移到提交阶段:
# .pre-commit-config.yaml
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.5.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-added-large-files
args: ['--maxkb=1000']
- id: check-case-conflict
- id: check-merge-conflict
- id: detect-private-key
- repo: https://github.com/psf/black
rev: 23.10.0
hooks:
- id: black
language_version: python3.11
- repo: https://github.com/pycqa/isort
rev: 5.12.0
hooks:
- id: isort
args: ["--profile", "black"]
- repo: https://github.com/pycqa/flake8
rev: 6.1.0
hooks:
- id: flake8
additional_dependencies: [flake8-docstrings]
- repo: https://github.com/pre-commit/mirrors-eslint
rev: v8.52.0
hooks:
- id: eslint
files: \.[jt]sx?$
types: [file]
additional_dependencies:
- eslint@8.52.0
- eslint-config-prettier@9.0.0
- eslint-plugin-react@7.33.2
- repo: https://github.com/pre-commit/mirrors-prettier
rev: v3.0.3
hooks:
- id: prettier
types_or: [css, javascript, jsx, typescript, tsx, json, yaml]
- repo: local
hooks:
- id: unit-tests
name: Run unit tests
entry: npm run test:unit -- --passWithNoTests
language: system
pass_filenames: false
stages: [commit]
其中值得注意的细节:check-added-large-files 通过 --maxkb=1000 阻止超大文件入库;detect-private-key 直接拦截私钥误提交(呼应 SKILL.md 中“将密钥视为高风险”的安全要求);eslint 钩子用 files: \.[jt]sx?$ 限定只扫描 JS/TS/JSX/TSX;最后的 local 钩子把单元测试接入 stages: [commit],实现“提交即回归”。
再配合一键开发环境初始化脚本 scripts/setup-dev-environment.sh:
#!/bin/bash
# scripts/setup-dev-environment.sh
set -euo pipefail
echo "🚀 Setting up development environment..."
# Check prerequisites
check_prerequisites() {
echo "Checking prerequisites..."
commands=("git" "node" "npm" "docker" "docker-compose")
for cmd in "${commands[@]}"; do
if ! command -v "$cmd" &> /dev/null; then
echo "❌ $cmd is not installed"
exit 1
fi
done
echo "✅ All prerequisites installed"
}
# Install dependencies
install_dependencies() {
echo "Installing dependencies..."
npm ci
# Install global tools
npm install -g @commitlint/cli @commitlint/config-conventional
npm install -g semantic-release
# Install pre-commit
pip install pre-commit
pre-commit install
pre-commit install --hook-type commit-msg
}
# Setup local services
setup_services() {
echo "Setting up local services..."
# Create docker network
docker network create dev-network 2>/dev/null || true
# Start services
docker-compose -f docker-compose.dev.yml up -d
# Wait for services
echo "Waiting for services to be ready..."
./scripts/wait-for-services.sh
}
# Initialize database
initialize_database() {
echo "Initializing database..."
npm run db:migrate
npm run db:seed
}
# Setup environment variables
setup_environment() {
echo "Setting up environment variables..."
if [ ! -f .env.local ]; then
cp .env.example .env.local
echo "✅ Created .env.local from .env.example"
echo "⚠️ Please update .env.local with your values"
fi
}
# Main execution
main() {
check_prerequisites
install_dependencies
setup_services
setup_environment
initialize_database
echo "✅ Development environment setup complete!"
echo ""
echo "Next steps:"
echo "1. Update .env.local with your configuration"
echo "2. Run 'npm run dev' to start the development server"
echo "3. Visit http://localhost:3000"
}
main
该脚本用 set -euo pipefail 保证任何一步失败即中止;按“前置检查 → 依赖安装 → 本地服务 → 环境变量 → 数据库迁移/种子数据”的固定顺序执行,并把 pre-commit install --hook-type commit-msg(配合 commitlint)一并接入,让新成员在一条命令内获得与 CI 完全一致的质量基线。
六、基础设施自动化:Terraform 工作流与 PR 内嵌 Plan 评审
第 5 节给出基础设施即代码(IaC)的 CI 落地方式(.github/workflows/terraform.yml):
# .github/workflows/terraform.yml
name: Terraform
on:
pull_request:
paths:
- 'terraform/**'
- '.github/workflows/terraform.yml'
push:
branches:
- main
paths:
- 'terraform/**'
env:
TF_VERSION: '1.6.0'
TF_VAR_project_name: ${{ github.event.repository.name }}
jobs:
terraform:
name: Terraform Plan & Apply
runs-on: ubuntu-latest
defaults:
run:
working-directory: terraform
steps:
- uses: actions/checkout@v4
- name: Setup Terraform
uses: hashicorp/setup-terraform@v2
with:
terraform_version: ${{ env.TF_VERSION }}
terraform_wrapper: false
- name: Configure AWS Credentials
uses: aws-actions/configure-aws-credentials@v2
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region: us-east-1
- name: Terraform Format Check
run: terraform fmt -check -recursive
- name: Terraform Init
run: |
terraform init \
-backend-config="bucket=${{ secrets.TF_STATE_BUCKET }}" \
-backend-config="key=${{ github.repository }}/terraform.tfstate" \
-backend-config="region=us-east-1"
- name: Terraform Validate
run: terraform validate
- name: Terraform Plan
id: plan
run: |
terraform plan -out=tfplan -no-color | tee plan_output.txt
# Extract plan summary
echo "PLAN_SUMMARY<<EOF" >> $GITHUB_ENV
grep -E '(Plan:|No changes.|# )' plan_output.txt >> $GITHUB_ENV
echo "EOF" >> $GITHUB_ENV
- name: Comment PR
if: github.event_name == 'pull_request'
uses: actions/github-script@v6
with:
script: |
const output = `#### Terraform Plan 📖
\`\`\`
${process.env.PLAN_SUMMARY}
\`\`\`
*Pushed by: @${{ github.actor }}, Action: \`${{ github.event_name }}\`*`;
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: output
});
- name: Terraform Apply
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
run: terraform apply tfplan
核心机制是路径过滤 + Plan/Apply 分离:
paths:过滤让 terraform 工作流只在terraform/**或工作流自身变更时触发,避免无谓消耗;- 分支策略:PR 阶段只执行
fmt -check→init→validate→plan,绝不 apply;只有 push 到main时才执行terraform apply tfplan,且 apply 使用的是 PR 阶段产出的tfplan文件,保证“评审的即部署的”; - PR 评审增强:
grep -E '(Plan:|No changes.|# )'从 plan 输出中提炼增删改摘要,通过github-script直接以评论形式贴到 PR 上,评审人无需翻日志即可判断基础设施变更影响面; - 远程状态(backend)通过 secrets 注入 bucket/key/region,state 文件按
repo/terraform.tfstate组织,多仓库互不干扰。
七、监控与告警自动化:Helm 一键部署可观测性栈
第 6 节把监控栈也纳入自动化(.github/workflows/monitoring.yml):
# .github/workflows/monitoring.yml
name: Deploy Monitoring
on:
push:
paths:
- 'monitoring/**'
- '.github/workflows/monitoring.yml'
branches:
- main
jobs:
deploy-monitoring:
name: Deploy Monitoring Stack
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Helm
uses: azure/setup-helm@v3
with:
version: '3.12.0'
- name: Configure Kubernetes
run: |
echo "${{ secrets.KUBE_CONFIG }}" | base64 -d > kubeconfig
export KUBECONFIG=kubeconfig
- name: Add Helm repositories
run: |
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo add grafana https://grafana.github.io/helm-charts
helm repo update
- name: Deploy Prometheus
run: |
helm upgrade --install prometheus prometheus-community/kube-prometheus-stack \
--namespace monitoring \
--create-namespace \
--values monitoring/prometheus-values.yaml \
--wait
- name: Deploy Grafana Dashboards
run: |
kubectl apply -f monitoring/dashboards/
- name: Deploy Alert Rules
run: |
kubectl apply -f monitoring/alerts/
- name: Setup Alert Routing
run: |
helm upgrade --install alertmanager prometheus-community/alertmanager \
--namespace monitoring \
--values monitoring/alertmanager-values.yaml
设计要点:
- 同样以
paths限定触发范围(monitoring/**),--wait确保 Helm 部署完成后才进入下一步; - 使用
helm upgrade --install的幂等语义,重复执行不会产生重复资源; - 采用“代码即配置”的声明式管理:Dashboard 与告警规则都存放在仓库
monitoring/dashboards/、monitoring/alerts/目录,通过kubectl apply统一管理版本,让监控配置与业务代码共享同一套评审、审查与回滚流程;KubeConfig 经 base64 编码存入 secret,避免明文暴露。
八、依赖更新自动化:Renovate 配置
第 7 节给出依赖保鲜方案——Renovate 配置:
{
"extends": [
"config:base",
":dependencyDashboard",
":semanticCommits",
":automergeDigest",
":automergeMinor"
],
"schedule": ["after 10pm every weekday", "before 5am every weekday", "every weekend"],
"timezone": "America/New_York",
"vulnerabilityAlerts": {
"labels": ["security"],
"automerge": true
},
"packageRules": [
{
"matchDepTypes": ["devDependencies"],
"automerge": true
},
{
"matchPackagePatterns": ["^@types/"],
"automerge": true
},
{
"matchPackageNames": ["node"],
"enabled": false
},
{
"matchPackagePatterns": ["^eslint"],
"groupName": "eslint packages",
"automerge": true
},
{
"matchManagers": ["docker"],
"pinDigests": true
}
],
"postUpdateOptions": [
"npmDedupe",
"yarnDedupeHighest"
],
"prConcurrentLimit": 3,
"prCreation": "not-pending",
"rebaseWhen": "behind-base-branch",
"semanticCommitScope": "deps"
}
策略解读:
- 风险分级自动化:devDependencies 与
@types/*类型包自动合并(automerge),运行时依赖则留待人工评审;node本体更新被显式禁用(enabled: false),避免运行时大版本跳变; - 分组与去重:eslint 相关包按
groupName合并为一个 PR,减少噪音;postUpdateOptions开启npmDedupe/yarnDedupeHighest在更新后自动去重; - 节奏与限流:
schedule+timezone把更新 PR 收敛到夜间/周末,prConcurrentLimit: 3限制并发 PR 数量; - 安全优先:
vulnerabilityAlerts对漏洞告警打security标签并直接 automerge,保证安全修复不被阻塞; - Dockerfile 通过
pinDigests锁定镜像摘要(digest)而非可变 tag,提升供应链可复现性。
九、文档自动化:TypeDoc 生成、Mermaid 架构图与 Pages 发布
第 8 节实现“代码即文档”的自动生成链路(.github/workflows/docs.yml):
# .github/workflows/docs.yml
name: Documentation
on:
push:
branches: [main]
paths:
- 'src/**'
- 'docs/**'
- 'README.md'
jobs:
generate-docs:
name: Generate Documentation
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 18
- name: Install dependencies
run: npm ci
- name: Generate API docs
run: |
npm run docs:api
npm run docs:typescript
- name: Generate architecture diagrams
run: |
npm install -g @mermaid-js/mermaid-cli
mmdc -i docs/architecture.mmd -o docs/architecture.png
- name: Build documentation site
run: |
npm run docs:build
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs/dist
cname: docs.example.com
配套的 TypeScript 生成脚本(scripts/generate-docs.ts):
// scripts/generate-docs.ts
import { Application, TSConfigReader, TypeDocReader } from 'typedoc';
import { generateMarkdown } from './markdown-generator';
import { createApiReference } from './api-reference';
async function generateDocumentation() {
// TypeDoc for TypeScript documentation
const app = new Application();
app.options.addReader(new TSConfigReader());
app.options.addReader(new TypeDocReader());
app.bootstrap({
entryPoints: ['src/index.ts'],
out: 'docs/api',
theme: 'default',
includeVersion: true,
excludePrivate: true,
readme: 'README.md',
plugin: ['typedoc-plugin-markdown']
});
const project = app.convert();
if (project) {
await app.generateDocs(project, 'docs/api');
// Generate custom markdown docs
await generateMarkdown(project, {
output: 'docs/guides',
includeExamples: true,
generateTOC: true
});
// Create API reference
await createApiReference(project, {
format: 'openapi',
output: 'docs/openapi.json',
includeSchemas: true
});
}
// Generate architecture documentation
await generateArchitectureDocs();
// Generate deployment guides
await generateDeploymentGuides();
}
async function generateArchitectureDocs() {
const mermaidDiagrams = `
graph TB
A[Client] --> B[Load Balancer]
B --> C[Web Server]
C --> D[Application Server]
D --> E[Database]
D --> F[Cache]
D --> G[Message Queue]
`;
// Save diagrams and generate documentation
await fs.writeFile('docs/architecture.mmd', mermaidDiagrams);
}
关键收益:文档站点只在 src/**、docs/**、README.md 变更时重建;includeVersion: true 让 API 文档与版本号绑定;Mermaid 图源文件(.mmd)入库、PNG 由 CI 生成,架构图永远与代码同源;最终通过 peaceiris/actions-gh-pages 发布到 GitHub Pages 并可配置自定义域名 cname。
十、安全自动化:依赖、容器、源码与密钥的立体扫描
第 9 节的 Security Scan 工作流(.github/workflows/security.yml)把安全左移到每次 push 与每周定时:
# .github/workflows/security.yml
name: Security Scan
on:
push:
branches: [main, develop]
pull_request:
schedule:
- cron: '0 0 * * 0' # Weekly on Sunday
jobs:
security-scan:
name: Security Scanning
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Trivy vulnerability scanner
uses: aquasecurity/trivy-action@master
with:
scan-type: 'fs'
scan-ref: '.'
format: 'sarif'
output: 'trivy-results.sarif'
severity: 'CRITICAL,HIGH'
- name: Upload Trivy results
uses: github/codeql-action/upload-sarif@v2
with:
sarif_file: 'trivy-results.sarif'
- name: Run Snyk security scan
uses: snyk/actions/node@master
env:
SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
with:
args: --severity-threshold=high
- name: Run OWASP Dependency Check
uses: dependency-check/Dependency-Check_Action@main
with:
project: ${{ github.repository }}
path: '.'
format: 'ALL'
args: >
--enableRetired
--enableExperimental
- name: SonarCloud Scan
uses: SonarSource/sonarcloud-github-action@master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
- name: Run Semgrep
uses: returntocorp/semgrep-action@v1
with:
config: >-
p/security-audit
p/secrets
p/owasp-top-ten
- name: GitLeaks secret scanning
uses: gitleaks/gitleaks-action@v2
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
该工作流构建了四层防线:Trivy(scan-type: 'fs',仅保留 CRITICAL,HIGH,输出 SARIF 供 CodeQL 聚合展示)、Snyk(--severity-threshold=high 阻断高危依赖)、OWASP Dependency Check(扫描已知漏洞 CVE)、SonarCloud + Semgrep(静态代码分析与 OWASP Top 10 规则集)以及 GitLeaks(防密钥泄漏)。schedule: cron '0 0 * * 0' 每周日执行一次全量扫描,弥补 PR 增量扫描的盲区,与 SKILL.md 的“安全扫描 + 密钥处理”要求完全对应。
十一、复杂工作流编排:并行/串行/重试/超时的通用编排器
当 CI YAML 无法表达复杂流程(例如需要条件分支、并行扇出、带指数退避的重试)时,第 10 节给出一个 TypeScript 实现的事件驱动编排器(workflow-orchestrator.ts):
// workflow-orchestrator.ts
import { EventEmitter } from 'events';
import { Logger } from 'winston';
interface WorkflowStep {
name: string;
type: 'parallel' | 'sequential';
steps?: WorkflowStep[];
action?: () => Promise<any>;
retries?: number;
timeout?: number;
condition?: () => boolean;
onError?: 'fail' | 'continue' | 'retry';
}
export class WorkflowOrchestrator extends EventEmitter {
constructor(
private logger: Logger,
private config: WorkflowConfig
) {
super();
}
async execute(workflow: WorkflowStep): Promise<WorkflowResult> {
const startTime = Date.now();
const result: WorkflowResult = {
success: true,
steps: [],
duration: 0
};
try {
await this.executeStep(workflow, result);
} catch (error) {
result.success = false;
result.error = error;
this.emit('workflow:failed', result);
}
result.duration = Date.now() - startTime;
this.emit('workflow:completed', result);
return result;
}
private async executeStep(
step: WorkflowStep,
result: WorkflowResult,
parentPath: string = ''
): Promise<void> {
const stepPath = parentPath ? `${parentPath}.${step.name}` : step.name;
this.emit('step:start', { step: stepPath });
// Check condition
if (step.condition && !step.condition()) {
this.logger.info(`Skipping step ${stepPath} due to condition`);
this.emit('step:skipped', { step: stepPath });
return;
}
const stepResult: StepResult = {
name: step.name,
path: stepPath,
startTime: Date.now(),
success: true
};
try {
if (step.action) {
// Execute single action
await this.executeAction(step, stepResult);
} else if (step.steps) {
// Execute sub-steps
if (step.type === 'parallel') {
await this.executeParallel(step.steps, result, stepPath);
} else {
await this.executeSequential(step.steps, result, stepPath);
}
}
stepResult.endTime = Date.now();
stepResult.duration = stepResult.endTime - stepResult.startTime;
result.steps.push(stepResult);
this.emit('step:complete', { step: stepPath, result: stepResult });
} catch (error) {
stepResult.success = false;
stepResult.error = error;
result.steps.push(stepResult);
this.emit('step:failed', { step: stepPath, error });
if (step.onError === 'fail') {
throw error;
}
}
}
private async executeAction(
step: WorkflowStep,
stepResult: StepResult
): Promise<void> {
const timeout = step.timeout || this.config.defaultTimeout;
const retries = step.retries || 0;
let lastError: Error;
for (let attempt = 0; attempt <= retries; attempt++) {
try {
const result = await Promise.race([
step.action!(),
this.createTimeout(timeout)
]);
stepResult.output = result;
return;
} catch (error) {
lastError = error as Error;
if (attempt < retries) {
this.logger.warn(`Step ${step.name} failed, retry ${attempt + 1}/${retries}`);
await this.delay(this.calculateBackoff(attempt));
}
}
}
throw lastError!;
}
private async executeParallel(
steps: WorkflowStep[],
result: WorkflowResult,
parentPath: string
): Promise<void> {
await Promise.all(
steps.map(step => this.executeStep(step, result, parentPath))
);
}
private async executeSequential(
steps: WorkflowStep[],
result: WorkflowResult,
parentPath: string
): Promise<void> {
for (const step of steps) {
await this.executeStep(step, result, parentPath);
}
}
private createTimeout(ms: number): Promise<never> {
return new Promise((_, reject) => {
setTimeout(() => reject(new Error(`Timeout after ${ms}ms`)), ms);
});
}
private calculateBackoff(attempt: number): number {
return Math.min(1000 * Math.pow(2, attempt), 30000);
}
private delay(ms: number): Promise<void> {
return new Promise(resolve => setTimeout(resolve, ms));
}
}
编排器的核心能力:
- 声明式工作流树:
WorkflowStep递归支持parallel/sequential两种组合类型,可嵌套任意深度,叶子节点挂action闭包; - 条件跳过:
condition()返回 false 时跳过该步并发出step:skipped事件; - 超时与重试:
Promise.race实现超时熔断(timeout默认值来自config.defaultTimeout);重试采用指数退避(1000 * 2^attempt,上限 30 秒),避免失败风暴压垮下游; - 错误策略:每步可声明
onError: 'fail' | 'continue' | 'retry',配合事件订阅(workflow:failed/workflow:completed/step:failed等)实现可观测的编排运行。
配套的部署工作流示例(组合全部特性):
// Example workflow definition
export const deploymentWorkflow: WorkflowStep = {
name: 'deployment',
type: 'sequential',
steps: [
{
name: 'pre-deployment',
type: 'parallel',
steps: [
{
name: 'backup-database',
action: async () => {
// Backup database
},
timeout: 300000 // 5 minutes
},
{
name: 'health-check',
action: async () => {
// Check system health
},
retries: 3
}
]
},
{
name: 'deployment',
type: 'sequential',
steps: [
{
name: 'blue-green-switch',
action: async () => {
// Switch traffic to new version
},
onError: 'retry',
retries: 2
},
{
name: 'smoke-tests',
action: async () => {
// Run smoke tests
},
onError: 'fail'
}
]
},
{
name: 'post-deployment',
type: 'parallel',
steps: [
{
name: 'notify-teams',
action: async () => {
// Send notifications
},
onError: 'continue'
},
{
name: 'update-monitoring',
action: async () => {
// Update monitoring dashboards
}
}
]
}
]
};
该示例演示了经典的蓝绿部署三段式:部署前并行执行数据库备份(5 分钟超时)与健康检查(最多重试 3 次);部署阶段蓝绿切换失败可重试 2 次、冒烟测试失败则整体 fail;部署后通知团队(失败也 continue,不阻断主流程)与更新监控面板并行执行。这正好呼应 SKILL.md 的安全要求——部署步骤必须伴随回滚预案(此处即蓝绿切换机制)。
十二、输出格式与实施落地步骤
实施手册最后明确了技能产出的十项交付物清单,也是整个自动化工程的验收框架:
- Workflow Analysis:当前流程盘点与自动化机会清单;
- CI/CD Pipeline:完整的 GitHub Actions / GitLab CI 配置;
- Release Automation:语义化版本与发布工作流;
- Development Automation:pre-commit 钩子与开发环境脚本;
- Infrastructure Automation:Terraform 与 Kubernetes 工作流;
- Security Automation:扫描与合规工作流;
- Documentation Generation:自动化的文档与图表;
- Workflow Orchestration:复杂工作流管理;
- Monitoring Integration:自动化告警与仪表盘;
- Implementation Guide:逐步安装指导。
落地的推荐执行顺序:先用第 2 节的 WorkflowAnalyzer 输出盘点报告 → 搭建第 3 节的多环境 CI/CD 骨架 → 接入第 5 节 pre-commit 钩子形成开发侧质量门禁 → 引入第 4 节语义化发布 → 按需补充 Terraform(第 6 节)、监控(第 7 节)、依赖更新(第 8 节)、文档(第 9 节)与安全扫描(第 10 节)→ 复杂度上升后再引入第 11 节的编排器。自始至终遵循“减少人工操作的同时保持质量与安全标准”这一原则。
十三、仓库内真实印证:AAS 自身如何实践 CI
上述模式并非纸上谈兵。AAS 仓库自身的 .github/workflows/ci.yml 就体现了本技能的核心设计思想:
- 多阶段门禁与依赖编排:工作流拆分为
pr-policy、source-validation、pr-evidence、artifact-preview、main-validation-and-sync多个 job,通过needs:建立依赖链(如source-validation依赖pr-policy、artifact-preview依赖前两者),与第 3 节“质量 → 测试 → 构建 → 部署 → 验证”的阶段门禁思想一致; - 缓存与确定性构建:使用
actions/setup-node的cache: 'npm'、npm ci --ignore-scripts --audit=false保证安装可复现,与流水线示例中的缓存与npm ci用法同源; - 安全左移:
main-validation-and-sync阶段执行npm audit --audit-level=high(并带重试与限速),source-validation运行npm run security:docs,对应第 9 节的安全扫描要求; - 审批与回滚边界:
canonical-sync分支的 PR 必须由受信任 bot 发起、路径边界受限、并“字节级可复现”校验,merge_canonical_sync_pr.cjs在精确检查通过后才合并——这是“未经审批不执行高风险步骤”这一安全原则的工程化体现; - 制品可追溯:构建产物通过
upload-artifact上传并附带retention-days,PR 阶段生成preview_manifest.json摘要,与示例中的BUILD_NUMBER/COMMIT_SHA注入思路一致。
同时,技能元数据(类别、风险、触发词)被收录于 data/catalog.json 与仓库根目录的 skills_index.json,Agent 可通过本地索引直接检索到该技能并加载 SKILL.md,再按需打开 implementation-playbook.md 获取上述全部可执行配置。需要说明的是,本技能产出的工作流文件属于“建议与模板”,在任何环境中启用前都必须在目标仓库内完成环境特异性验证、真实测试与专家评审——这正是 SKILL.md Limitations 部分反复强调的边界。