agentic-awesome-skills 工作流自动化技能实战:CI/CD 流水线、发布、基础设施与安全自动化的完整实施指南

原创2026-09-23 12:07:541,974 阅读
文章标签:人工智能AI 技能AI 插件MCP 服务开发工具AI 应用

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 的安全要求——部署步骤必须伴随回滚预案(此处即蓝绿切换机制)。

十二、输出格式与实施落地步骤

实施手册最后明确了技能产出的十项交付物清单,也是整个自动化工程的验收框架:

  1. Workflow Analysis:当前流程盘点与自动化机会清单;
  2. CI/CD Pipeline:完整的 GitHub Actions / GitLab CI 配置;
  3. Release Automation:语义化版本与发布工作流;
  4. Development Automation:pre-commit 钩子与开发环境脚本;
  5. Infrastructure Automation:Terraform 与 Kubernetes 工作流;
  6. Security Automation:扫描与合规工作流;
  7. Documentation Generation:自动化的文档与图表;
  8. Workflow Orchestration:复杂工作流管理;
  9. Monitoring Integration:自动化告警与仪表盘;
  10. 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 部分反复强调的边界。

登录后查看全文
agentic-awesome-skills