Back to Details

ci-cd

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CI/CD Pipelines: Multi-Platform Production Infrastructure

CI/CD流水线：跨平台生产基础设施

Write, review, and architect CI/CD pipelines across GitHub Actions, GitLab CI/CD, and Forgejo CI/CD. The goal is secure, fast, auditable pipelines that satisfy both engineering needs and compliance requirements (PCI-DSS 4.0).
Target versions (March 2026):
  • GitHub Actions: ubuntu-24.04 runners (ubuntu-latest), arm64 GA, artifact v4, attestations GA
  • GitLab CI/CD: GitLab 18.10, CI/CD Catalog GA, CI Components with typed 
    spec: inputs
  • Forgejo CI/CD: Forgejo v14.0, Runner v12.7.x (multi-connection support since v12.7.0)
  • Supply chain: cosign v3.x (Sigstore), Syft/Trivy for SBOM, SLSA v1.0
This skill covers four domains depending on context:
  • Workflow design -- stages, jobs, caching, artifacts, parallelism, reusable patterns
  • Security -- supply chain hardening, SHA pinning, secret management, OIDC, least-privilege
  • Compliance -- PCI-DSS 4.0 Req 6.x mapping, SBOM generation, signed artifacts, audit trails
  • Cross-platform -- writing pipelines that work across GitHub/GitLab/Forgejo, migration patterns
支持编写、评审和架构基于GitHub Actions、GitLab CI/CD、Forgejo CI/CD的CI/CD流水线，目标是构建安全、高效、可审计的流水线，同时满足工程需求和合规要求（PCI-DSS 4.0）。
目标版本（2026年3月）：
  • GitHub Actions：ubuntu-24.04 runners（ubuntu-latest）、arm64 GA、artifact v4、attestations GA
  • GitLab CI/CD：GitLab 18.10、CI/CD Catalog GA、支持带类型
    spec: inputs
    的CI Components
  • Forgejo CI/CD：Forgejo v14.0、Runner v12.7.x（v12.7.0起支持多连接）
  • 供应链：cosign v3.x（Sigstore）、用于SBOM生成的Syft/Trivy、SLSA v1.0
本技能根据场景覆盖四个领域：
  • 工作流设计——阶段、任务、缓存、制品、并行执行、可复用模式
  • 安全——供应链加固、SHA pinning、密钥管理、OIDC、最小权限原则
  • 合规——PCI-DSS 4.0 需求6.x映射、SBOM生成、制品签名、审计追踪
  • 跨平台——编写可在GitHub/GitLab/Forgejo上运行的流水线、迁移方案

When to use

适用场景

  • Writing or reviewing CI/CD pipeline configs (workflows, 
    .gitlab-ci.yml
    , Forgejo actions)
  • Designing pipeline architecture (stages, parallelism, caching, deployment strategies)
  • Hardening pipelines against supply chain attacks (SHA pinning, image signing, provenance)
  • Setting up security scanning in CI (SAST, SCA, container scanning, secret detection)
  • Configuring runners, caching strategies, or artifact management
  • PCI-DSS 4.0 compliance for CI/CD (Req 6.2.1, 6.2.4, 6.3.2, 6.4.2, 6.5.3)
  • Migrating pipelines between platforms (GitLab -> GitHub, GitHub -> Forgejo)
  • Troubleshooting failed pipelines, flaky jobs, or runner issues
  • 编写或评审CI/CD流水线配置（工作流、
    .gitlab-ci.yml
    、Forgejo actions）
  • 设计流水线架构（阶段、并行执行、缓存、部署策略）
  • 加固流水线防范供应链攻击（SHA pinning、镜像签名、溯源）
  • 在CI中配置安全扫描（SAST、SCA、容器扫描、密钥检测）
  • 配置runners、缓存策略或制品管理
  • CI/CD的PCI-DSS 4.0合规适配（需求6.2.1、6.2.4、6.3.2、6.4.2、6.5.3）
  • 在不同平台间迁移流水线（GitLab -> GitHub、GitHub -> Forgejo）
  • 排查流水线失败、任务不稳定或runner相关问题

When NOT to use

不适用场景

  • Kubernetes manifests, Helm charts, cluster architecture -- use kubernetes
  • Dockerfiles, Compose stacks, container image optimization -- use docker
  • Terraform/OpenTofu infrastructure-as-code -- use terraform
  • Ansible playbooks, configuration management -- use ansible
  • Security audits of application code (SAST findings, auth bugs) -- use security-audit
  • Code review of pipeline-adjacent code (the app itself) -- use code-review
  • The code-review skill has a 
    cicd-pipelines.md
    reference for bug patterns in existing pipelines. This skill is for writing and architecting pipelines.
  • Kubernetes清单、Helm charts、集群架构——使用kubernetes技能
  • Dockerfile、Compose栈、容器镜像优化——使用docker技能
  • Terraform/OpenTofu基础设施即代码——使用terraform技能
  • Ansible playbook、配置管理——使用ansible技能
  • 应用代码安全审计（SAST发现、认证漏洞）——使用security-audit技能
  • 流水线周边代码（应用本身）的代码评审——使用code-review技能
  • code-review技能包含
    cicd-pipelines.md
    参考文档，覆盖现有流水线的bug模式，本技能专注于流水线的编写和架构设计。

AI Self-Check

AI自检清单

AI tools consistently produce the same CI/CD mistakes. Before returning any generated pipeline config, verify against this list:
  • SHA pinning: all third-party actions/images pinned to full commit SHA or digest, not mutable tags. Add 
    # vX.Y.Z
    comment for readability.
  • Permissions: explicit 
    permissions:
    block on every GitHub Actions workflow (read-only default). GitLab: protected variables scoped correctly.
  • No secrets in config: no hardcoded tokens, passwords, or API keys. Use CI/CD secret variables or vault integration.
  • No 
    latest
    tags    : runner images, tool images, and base images pinned to specific versions or SHA256 digests.
  • Caching strategy: dependencies cached correctly (lockfile-based keys), build outputs use artifacts (not cache).
  • Fail-fast security: SAST, dependency scanning, and secret detection run early (not after deployment).
  • Manual gates for production: production deployments require explicit approval (not auto-deploy on merge).
  • SBOM generation: release pipelines generate and attach SBOMs (SPDX or CycloneDX). Required for PCI-DSS 4.0.
  • Minimal scope: jobs have minimum required permissions, access only needed secrets, and run only needed steps.
  • No 
    allow_failure
    without justification    : if a job can fail, explain why in a comment.
  • Version pinning on tools: 
    node:22
    , not 
    node:lts
    . 
    python:3.13
    , not 
    python:3
    . Specific versions prevent silent breakage.
  • Trigger scoping: 
    on: push
    without branch/path filters runs on every push to every branch -- scope to 
    branches: [main]
    and/or 
    paths:
    filters. Same for GitLab: 
    rules:
    with 
    if
    conditions, not bare 
    only: [pushes]
    .
  • No expression injection (GitHub Actions): 
    ${{ }}
    expressions never used directly in 
    run:
    blocks. Assign to 
    env:
    first. 
    github.event.*
    is attacker-controlled. Avoid 
    github.ref_name
    in security-sensitive contexts (injectable via crafted tag/branch names).
AI工具生成CI/CD配置时常犯同类错误，返回任何生成的流水线配置前，请对照以下清单验证：
  • SHA pinning：所有第三方action/镜像都绑定完整的提交SHA或摘要，而非可变标签。添加
    # vX.Y.Z
    注释提升可读性。
  • 权限：每个GitHub Actions工作流都显式配置
    permissions:
    块（默认只读）。GitLab：受保护变量的作用域配置正确。
  • 配置中无密钥：没有硬编码的token、密码或API密钥，使用CI/CD密钥变量或密钥管理服务集成。
  • 不使用
    latest
    标签    ：runner镜像、工具镜像和基础镜像都绑定到特定版本或SHA256摘要。
  • 缓存策略：依赖项缓存配置正确（基于锁文件的key），构建输出使用制品存储（而非缓存）。
  • 安全校验前置：SAST、依赖扫描、密钥检测在流水线早期执行（而非部署后）。
  • 生产环境手动审批门：生产部署需要显式审批（不得合并后自动部署）。
  • SBOM生成：发布流水线生成并附带SBOM（SPDX或CycloneDX格式），这是PCI-DSS 4.0的强制要求。
  • 最小作用域：任务仅配置必要的权限、仅访问所需密钥、仅执行必要步骤。
  • 无正当理由不得使用
    allow_failure
    ：如果允许任务失败，需要添加注释说明原因。
  • 工具版本固定：使用
    node:22
    而非
    node:lts
    ，使用
    python:3.13
    而非
    python:3
    ，固定版本可避免静默故障。
  • 触发条件限定：不带分支/路径过滤的
    on: push
    会在所有分支的每次推送时执行，需要限定到
    branches: [main]
    和/或
    paths:
    过滤。GitLab同理：使用带
    if
    条件的
    rules:
    ，而非裸写
    only: [pushes]
    。
  • 无表达式注入风险（GitHub Actions）：
    ${{ }}
    表达式不得直接用于
    run:
    块中，需先赋值给
    env:
    变量。
    github.event.*
    属于攻击者可控内容，在安全敏感场景避免使用
    github.ref_name
    （可通过构造标签/分支名注入）。

Workflow

工作流

Step 1: Identify the platform

步骤1：确认平台

SignalPlatform
.github/workflows/*.yml
GitHub Actions
.gitlab-ci.yml
GitLab CI/CD
.forgejo/workflows/*.yml
Forgejo CI/CD
User says "work" / "gitlab" / 
glab
GitLab CI/CD
User says "home" / "forgejo" / "gitea"Forgejo CI/CD
User says "github" / "ghcr" / 
gh
GitHub Actions
If unclear, ask. The platforms have significant differences despite surface similarity.
识别信号对应平台
.github/workflows/*.yml
GitHub Actions
.gitlab-ci.yml
GitLab CI/CD
.forgejo/workflows/*.yml
Forgejo CI/CD
用户提到"work"/"gitlab"/
glab
GitLab CI/CD
用户提到"home"/"forgejo"/"gitea"Forgejo CI/CD
用户提到"github"/"ghcr"/
gh
GitHub Actions
如果不明确请询问用户，不同平台尽管表面相似，但实际存在显著差异。

Step 2: Determine the domain

步骤2：确定领域

  • "Create a CI pipeline for my project" -> Workflow design
  • "Harden my pipeline" / "pin actions" -> Security
  • "Make this PCI compliant" / "SBOM" -> Compliance
  • "Port this from GitLab to GitHub" -> Cross-platform
  • "为我的项目创建CI流水线" -> 工作流设计
  • "加固我的流水线"/"固定action版本" -> 安全
  • "满足PCI合规要求"/"SBOM" -> 合规
  • "将这个从GitLab迁移到GitHub" -> 跨平台

Step 3: Gather requirements

步骤3：收集需求

Before writing pipeline config:
  • What triggers the pipeline? Push, PR/MR, tag, schedule, manual
  • What does it build? Language, runtime, package manager, build tool
  • What does it test? Unit, integration, e2e, linting, typechecking
  • Where does it deploy? K8s, Docker registry, cloud, bare metal
  • What compliance requirements? PCI-DSS, SOC 2, internal policies
  • Self-hosted or managed runners? Affects available tools and caching
编写流水线配置前确认以下信息：
  • 流水线触发条件是什么？ 推送、PR/MR、标签、定时、手动触发
  • 构建内容是什么？ 语言、运行时、包管理器、构建工具
  • 测试内容是什么？ 单元测试、集成测试、e2e测试、语法检查、类型检查
  • 部署目标是什么？ K8s、Docker镜像仓库、云服务、物理机
  • 有什么合规要求？ PCI-DSS、SOC 2、内部政策
  • 使用自托管还是托管runner？ 会影响可用工具和缓存配置

Step 4: Apply platform-specific patterns

步骤4：应用平台专属模式

Read the appropriate reference file:
  • GitHub Actions: 
    references/github-actions.md
  • GitLab CI/CD: 
    references/gitlab-ci.md
  • Supply chain / compliance: 
    references/supply-chain.md
For Forgejo CI/CD, see the Forgejo section below (smaller scope, inline).
阅读对应的参考文档：
  • GitHub Actions：
    references/github-actions.md
  • GitLab CI/CD：
    references/gitlab-ci.md
  • 供应链/合规：
    references/supply-chain.md
Forgejo CI/CD请参考下文的Forgejo章节（覆盖范围更小，直接内嵌说明）。

Step 5: Verify against AI Self-Check

步骤5：对照AI自检清单验证

Run through the checklist above before returning any generated config.
返回任何生成的配置前，都要完整走一遍上述检查清单。

Cross-Platform Patterns

跨平台通用模式

Stage ordering (all platforms)

阶段顺序（所有平台通用）

lint -> test -> build -> scan -> deploy
  1. Lint first -- fastest feedback, catches formatting/syntax early
  2. Test -- unit tests, typechecking
  3. Build -- compile, bundle, create artifacts
  4. Scan -- SAST, dependency audit, container scan (on build output)
  5. Deploy -- staging auto, production manual
lint -> test -> build -> scan -> deploy
  1. 语法检查优先——最快的反馈，可提前发现格式/语法问题
  2. 测试——单元测试、类型检查
  3. 构建——编译、打包、生成制品
  4. 扫描——SAST、依赖审计、容器扫描（针对构建输出）
  5. 部署—— staging环境自动部署，生产环境手动部署

Caching strategy

缓存策略

WhatCache keyPlatform notes
npm/bun
${{ hashFiles('**/package-lock.json') }}
or lockb		GH: 
actions/cache
. GL: 
cache:key:files
. Forgejo: same as GH.
pip
${{ hashFiles('**/requirements*.txt') }}
GH: cache action. GL: cache with 
$CI_COMMIT_REF_SLUG
prefix.
Go
${{ hashFiles('**/go.sum') }}
GH: 
actions/setup-go
has built-in cache.
Docker layersBuildKit cache mount or registry cacheGH: 
--cache-from type=gha
. GL: 
--cache-from $CI_REGISTRY_IMAGE:cache
.
Rule: cache is a speed optimization, not a correctness mechanism. Artifacts are for inter-job data. Cache may evict at any time -- pipelines must work without it.
缓存内容缓存key平台说明
npm/bun
${{ hashFiles('**/package-lock.json') }}
或 lockb		GitHub: 
actions/cache
。GitLab: 
cache:key:files
。Forgejo: 与GitHub一致。
pip
${{ hashFiles('**/requirements*.txt') }}
GitHub: cache action。GitLab: 缓存添加
$CI_COMMIT_REF_SLUG
前缀。
Go
${{ hashFiles('**/go.sum') }}
GitHub: 
actions/setup-go
内置缓存。
Docker层BuildKit缓存挂载或镜像仓库缓存GitHub: 
--cache-from type=gha
。GitLab: 
--cache-from $CI_REGISTRY_IMAGE:cache
。
规则：缓存是速度优化手段，而非正确性保障机制，制品用于任务间数据传递。缓存随时可能被淘汰——流水线在无缓存的情况下也必须能正常运行。

Secret management

密钥管理

PlatformMechanismScope control
GitHubRepository/org/environment secretsPer-environment, per-repo, per-org. Deployment branches.
GitLabCI/CD variables (project/group/instance)Protected branches/tags, environments, masked in logs.
ForgejoRepository/org secretsPer-repo, per-org. No environment scoping yet.
All platforms: never echo secrets, never pass as CLI args (visible in 
ps
), never write to artifacts. Use environment variables or file-based injection.
平台实现机制作用域控制
GitHub仓库/组织/环境密钥按环境、按仓库、按组织配置，支持部署分支限制。
GitLabCI/CD变量（项目/组/实例级别）受保护分支/标签、环境限制，日志自动掩码。
Forgejo仓库/组织密钥按仓库、按组织配置，暂不支持环境级作用域。
所有平台通用规则：永远不要打印密钥、不要将密钥作为CLI参数传递（可在
ps
中被看到）、不要写入制品，使用环境变量或文件注入方式传递。

Deployment gates

部署门控

EnvironmentTriggerApproval
Dev/PreviewEvery PR/MR pushNone
StagingMerge to mainNone (auto-deploy)
ProductionTag or manual dispatchRequired reviewer(s)
GitLab: 
when: manual
+ 
environment:
. GitHub: 
environment:
with protection rules. Forgejo: manual dispatch (
workflow_dispatch
).
环境触发条件审批要求
开发/预览环境每次PR/MR推送无需审批
Staging环境合并到main分支无需审批（自动部署）
生产环境打标签或手动触发需要指定审批人
GitLab：
when: manual
+ 
environment:
配置。GitHub：配置带保护规则的
environment:
。Forgejo：手动触发（
workflow_dispatch
）。

Monorepo Patterns

Monorepo适配模式

When a repo contains multiple services sharing a common library:
当仓库包含多个共享公共库的服务时使用以下模式：

Path-based triggering

基于路径的触发

  • GitHub Actions: 
    on.push.paths
    / 
    on.pull_request.paths
    to scope workflows per service
  • GitLab CI/CD: 
    rules: changes: paths:
    with 
    compare_to: refs/heads/main
  • Forgejo: same as GitHub Actions (
    on.push.paths
    )
  • GitHub Actions：使用
    on.push.paths
    /
    on.pull_request.paths
    按服务限定工作流触发范围
  • GitLab CI/CD：使用
    rules: changes: paths:
    搭配
    compare_to: refs/heads/main
  • Forgejo：与GitHub Actions一致（
    on.push.paths
    ）

Shared library detection

共享库变更检测

If 
libs/common/
changes, rebuild all services that depend on it:
  • List dependent services in a matrix or trigger all service workflows
  • paths
    filters accept globs: 
    paths: ['services/api/**', 'libs/common/**']
如果
libs/common/
发生变更，重建所有依赖该库的服务：
  • 在矩阵中列出所有依赖服务或触发所有服务的工作流
  • paths
    过滤器支持通配符：
    paths: ['services/api/**', 'libs/common/**']

Selective builds

选择性构建

Build only what changed. Two approaches:
  1. Per-service workflows with 
    paths:
    filters (simplest, recommended)
  2. Single workflow with matrix + change detection job that outputs which services need building
Rule: always rebuild when the shared lib changes. A "nothing changed" optimization that misses a shared dependency is worse than rebuilding everything.
仅构建变更的内容，有两种实现方式：
  1. 按服务拆分工作流搭配
    paths:
    过滤器（最简单，推荐）
  2. 单工作流加矩阵+变更检测任务，输出需要构建的服务列表
规则：共享库变更时必须重建所有服务，遗漏共享依赖变更的「无变更跳过」优化比重建所有服务的危害更大。

Forgejo CI/CD

Forgejo CI/CD

Forgejo Actions is "designed to be familiar, not designed to be compatible" with GitHub Actions. It reuses the workflow syntax but makes no compatibility guarantees.
Forgejo Actions的设计目标是「使用习惯贴近GitHub Actions但不保证兼容」，它复用了工作流语法，但不提供兼容性承诺。

Key differences from GitHub Actions

与GitHub Actions的核心差异

FeatureGitHub ActionsForgejo Actions
permissions:
Controls GITHUB_TOKEN scopeNot enforced -- token always has full rw (read-only for fork PRs)
continue-on-error:
 (job level)		Allows job failure without failing workflowNot supported -- step-level only
Runner imagesManaged 
ubuntu-24.04
with 200+ tools		Self-hosted, typically lean Debian/Alpine
Action resolution
actions/checkout@v4
-> github.com		Resolves from Forgejo mirror (configurable)
OIDC
permissions: id-token: write
enable-openid-connect
key
Workflow call defaults
inputs.<id>.default
populated		Always empty
Matrix + dynamic runs-onSupportedSupported since v14.0
LXC executionNot supportedSupported (Forgejo-specific)
功能GitHub ActionsForgejo Actions
permissions:
控制GITHUB_TOKEN的作用域不生效——token始终有完整读写权限（fork PR仅为只读）
任务级
continue-on-error:
允许任务失败但不标记整个工作流失败不支持——仅支持步骤级配置
Runner镜像托管的
ubuntu-24.04
内置200+工具		自托管，通常为精简的Debian/Alpine镜像
Action解析来源
actions/checkout@v4
-> github.com		从Forgejo镜像站解析（可配置）
OIDC
permissions: id-token: write
配置		通过
enable-openid-connect
字段配置
工作流调用默认值自动填充
inputs.<id>.default
始终为空
矩阵+动态runs-on支持v14.0起支持
LXC执行不支持支持（Forgejo专属特性）

Forgejo workflow template

Forgejo工作流模板

yaml
name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  ci:
    runs-on: docker                    # self-hosted runner label
    container:
      image: oven/bun:1.2             # pin to minor version minimum
    steps:
      - uses: actions/checkout@<sha>  # pin to SHA; resolves from Forgejo mirror
      - run: bun install --frozen-lockfile
      - run: bun run lint
      - run: bun run typecheck
      - run: bun run test
yaml
name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  ci:
    runs-on: docker                    # 自托管runner标签
    container:
      image: oven/bun:1.2             # 至少固定到次要版本
    steps:
      - uses: actions/checkout@<sha>  # 绑定到SHA，从Forgejo镜像站解析
      - run: bun install --frozen-lockfile
      - run: bun run lint
      - run: bun run typecheck
      - run: bun run test

Forgejo-specific gotchas

Forgejo专属注意事项

  • No 
    ubuntu-latest
     -- 
    runs-on
    maps to your registered runner labels (e.g., 
    docker
    )
  • Missing tools -- Forgejo runner containers are lean. Add 
    apt-get install
    for git, curl, etc.
  • TLS certs -- if Forgejo uses self-signed or internal CA certs, configure the runner's trust store (
    GIT_SSL_CAINFO=/path/to/ca-bundle.crt
    ) or install the CA into the container image. 
    GIT_SSL_NO_VERIFY=true
    is a last resort for dev/test only -- never normalize TLS bypass in production
  • Third-party actions -- many GitHub Marketplace actions use GitHub-specific API calls and will silently fail
  • Secrets in Forgejo -- 
    ${{ secrets.* }}
    works, but no environment-level scoping
  • permissions:
    not enforced     -- Forgejo parses the field but does not restrict the workflow token. The token always has full read-write access (read-only for fork PRs only). Don't assume least-privilege from 
    permissions:
    alone -- it has no effect on Forgejo.
  • 没有
    ubuntu-latest
    ——
    runs-on
    对应你注册的runner标签（例如
    docker
    ）
  • 工具缺失——Forgejo runner容器非常精简，需要通过
    apt-get install
    安装git、curl等工具
  • TLS证书——如果Forgejo使用自签名或内部CA证书，需要配置runner的信任库（
    GIT_SSL_CAINFO=/path/to/ca-bundle.crt
    ）或将CA安装到容器镜像中。
    GIT_SSL_NO_VERIFY=true
    仅为开发/测试场景的最后手段——永远不要在生产环境中默认绕过TLS校验
  • 第三方Action兼容性——很多GitHub Marketplace的action使用了GitHub专属API调用，会静默失败
  • Forgejo中的密钥——
    ${{ secrets.* }}
    可用，但不支持环境级作用域
  • permissions:
    不生效    ——Forgejo会解析该字段但不会限制工作流token的权限，token始终有完整读写权限（仅fork PR为只读）。不要认为仅配置
    permissions:
    就能实现最小权限——在Forgejo中该配置没有效果。

Forgejo release workflow pattern

Forgejo发布工作流模式

yaml
name: Release
on:
  push:
    tags: ['v*']

jobs:
  build-and-push:
    runs-on: docker
    container:
      image: catthehacker/ubuntu:act-24.04    # heavier image for multi-tool needs
    env:
      # Prefer GIT_SSL_CAINFO with your CA cert; this bypass is a last resort
      GIT_SSL_NO_VERIFY: "true"               # if cert is periodically expired
    steps:
      - uses: actions/checkout@<sha>  # pin to SHA; resolves from Forgejo mirror
      - name: Login to registry
        env:
          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
          HOST: ${{ secrets.REGISTRY_HOST }}
          USER: ${{ secrets.REGISTRY_USER }}
        run: echo "$TOKEN" | docker login "$HOST" -u "$USER" --password-stdin
      - name: Build and push
        env:
          REGISTRY: ${{ secrets.REGISTRY_HOST }}/${{ secrets.REGISTRY_IMAGE }}
          TAG: ${{ github.ref_name }}
        run: |
          docker build -t "$REGISTRY:$TAG" .
          docker push "$REGISTRY:$TAG"
Note: use secrets for registry host/image to avoid hardcoding private domains in git history.
yaml
name: Release
on:
  push:
    tags: ['v*']

jobs:
  build-and-push:
    runs-on: docker
    container:
      image: catthehacker/ubuntu:act-24.04    # 包含更多工具的镜像，适合多工具需求场景
    env:
      # 优先使用GIT_SSL_CAINFO配置CA证书，该绕过方案仅为最后手段
      GIT_SSL_NO_VERIFY: "true"               # 证书定期过期时临时使用
    steps:
      - uses: actions/checkout@<sha>  # 绑定到SHA，从Forgejo镜像站解析
      - name: Login to registry
        env:
          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
          HOST: ${{ secrets.REGISTRY_HOST }}
          USER: ${{ secrets.REGISTRY_USER }}
        run: echo "$TOKEN" | docker login "$HOST" -u "$USER" --password-stdin
      - name: Build and push
        env:
          REGISTRY: ${{ secrets.REGISTRY_HOST }}/${{ secrets.REGISTRY_IMAGE }}
          TAG: ${{ github.ref_name }}
        run: |
          docker build -t "$REGISTRY:$TAG" .
          docker push "$REGISTRY:$TAG"
注意：镜像仓库地址/镜像名称使用密钥存储，避免在git历史中硬编码私有域名。

PCI-DSS 4.0: CI/CD Compliance Mapping

PCI-DSS 4.0：CI/CD合规映射

All future-dated requirements became mandatory March 31, 2025.
PCI-DSS ReqWhat it means for CI/CDImplementation
6.2.1Secure development training + OWASP-aware processesSAST on every PR/MR, dependency scanning, secret detection
6.2.4Access control + change trackingBranch protection, required reviewers, signed commits, audit logs
6.3.2Software inventory (SBOM)Generate SPDX/CycloneDX SBOM per release, attach to artifacts
6.4.2Changes approved, documented, testedGated deployments, required approvals for prod, IaC audit trails
6.5.3Consistent security controls across environmentsSame scanning in dev/staging/prod, not just prod
Customized Approach (v4.0.1): automated CI/CD controls can satisfy manual review requirements if properly documented. An automated SAST/DAST/SCA gate with evidence = equivalent to manual code review for QSA assessment.
Read 
references/supply-chain.md
for detailed PCI-DSS compliance patterns.
所有未来生效的需求已于2025年3月31日强制生效。
PCI-DSS需求对CI/CD的要求实现方案
6.2.1安全开发培训+符合OWASP要求的流程每次PR/MR执行SAST、依赖扫描、密钥检测
6.2.4访问控制+变更追踪分支保护、强制审批、提交签名、审计日志
6.3.2软件资产清单（SBOM）每个版本生成SPDX/CycloneDX格式的SBOM，关联到对应制品
6.4.2变更经过审批、记录、测试部署门控、生产部署强制审批、IaC审计追踪
6.5.3跨环境的一致安全控制开发/staging/生产环境执行相同的扫描规则，而非仅在生产环境扫描
自定义适配方案（v4.0.1）：自动化CI/CD控制如果有完善的文档记录，可替代手动评审要求。带存证的自动化SAST/DAST/SCA门控在QSA评估中等同于手动代码评审。
阅读
references/supply-chain.md
了解详细的PCI-DSS合规实现模式。

AI-Age Considerations

AI时代注意事项

AI tools consistently generate insecure CI/CD configs: unpinned actions, missing 
permissions:
blocks, 
allow_failure: true
without justification, 
:latest
tags, secrets in 
run:
blocks. Always run the AI Self-Check against AI-generated pipeline code.
For detailed coverage of slopsquatting, AI agents in CI/CD, prompt injection in pipelines, and the OWASP Top 10 for Agentic Applications, read 
references/supply-chain.md
(AI-Age Supply Chain Risks section).
AI工具生成的CI/CD配置通常存在安全问题：未固定版本的action、缺失
permissions:
块、无正当理由的
allow_failure: true
、
:latest
标签、密钥直接写在
run:
块中。对AI生成的流水线代码必须执行AI自检清单校验。
关于依赖劫持、CI/CD中的AI Agent、流水线中的prompt注入、OWASP Agentic应用Top 10的详细说明，请阅读
references/supply-chain.md
的「AI时代供应链风险」章节。

Template Conventions

模板约定

  • @<sha>
     in GitHub Actions templates is a placeholder. Replace with the real 40-character commit SHA for the indicated version. Look up SHAs on the action's releases page or use Dependabot to manage them automatically.
  • Image tags in templates use floating minor versions (e.g., 
    oven/bun:1.2
    , 
    docker:27.5
    ) for readability. For production, pin to a specific patch version or SHA256 digest. The templates show the minimum acceptable granularity, not the ideal.
  • GitHub Actions模板中的**
    @<sha>
    **是占位符，替换为对应版本的真实40位提交SHA。可在action的发布页面查询SHA，或使用Dependabot自动管理。
  • 模板中的镜像标签使用浮动次要版本（例如
    oven/bun:1.2
    、
    docker:27.5
    ）提升可读性。生产环境请固定到具体的补丁版本或SHA256摘要，模板仅展示最低可接受的版本粒度，非最优实践。

Reference Files

参考文档

  • references/github-actions.md
    -- GitHub Actions patterns, templates, and security hardening
  • references/gitlab-ci.md
    -- GitLab CI/CD 18.x patterns, Catalog, Components, security
  • references/supply-chain.md
    -- supply chain security, incident timeline, SHA pinning, SBOM/SLSA, PCI-DSS compliance, image signing
  • references/github-actions.md
    ——GitHub Actions模式、模板、安全加固方案
  • references/gitlab-ci.md
    ——GitLab CI/CD 18.x模式、Catalog、Components、安全方案
  • references/supply-chain.md
    ——供应链安全、事件时间线、SHA pinning、SBOM/SLSA、PCI-DSS合规、镜像签名

Related Skills

相关技能

  • code-review -- has 
    references/cicd-pipelines.md
    for CI/CD bug patterns (expression injection, variable scoping, cache gotchas, ArgoCD sync issues)
  • security-audit -- for auditing application code, not pipeline code
  • docker -- for Dockerfile and container image optimization
  • kubernetes -- for K8s manifests and Helm charts that pipelines deploy to
  • git -- for git operations (commits, PRs/MRs, tags, releases) that trigger pipelines. CI/CD reacts to git events; git handles the operations that produce them.
  • code-review——包含
    references/cicd-pipelines.md
    ，覆盖CI/CD bug模式（表达式注入、变量作用域、缓存问题、ArgoCD同步问题）
  • security-audit——用于审计应用代码，而非流水线代码
  • docker——用于Dockerfile和容器镜像优化
  • kubernetes——用于流水线部署目标的K8s清单和Helm charts
  • git——用于触发流水线的git操作（提交、PRs/MRs、标签、发布）。CI/CD响应git事件，git负责生成事件的相关操作。

Rules

规则

  • Platform-first. Always confirm which CI/CD platform before writing config. GitHub Actions syntax that "mostly works" in Forgejo will silently break on edge cases.
  • SHA-pin everything. All third-party actions, all CI tool images. Tags are mutable. SHAs are not. The tj-actions, reviewdog, and Trivy compromises proved this is non-negotiable.
  • Secrets are sacred. Never log, echo, artifact, or pass as CLI arguments. Never use protected variables on unprotected branches.
  • Test the pipeline itself. 
    act
    (GitHub Actions local runner), 
    gitlab-ci-local
    , or dry-run modes. Don't discover pipeline bugs in production.
  • Cache != artifact. Cache is ephemeral speed optimization. Artifacts are guaranteed inter-job data. Confusing them causes intermittent failures.
  • Manual gates for prod. No exceptions. Auto-deploy to staging is fine. Auto-deploy to production is how incidents happen.
  • Scan early, deploy late. Security scanning in the first stages, deployment in the last. Finding a CVE after deployment is expensive.
  • PCI-DSS 4.0 is mandatory. If the pipeline touches CDE (cardholder data environment), SBOM generation, signed artifacts, and gated deployments are not optional.
  • 平台优先：编写配置前始终确认CI/CD平台。在Forgejo中「基本可用」的GitHub Actions语法会在边缘场景下静默失败。
  • 所有资源都绑定SHA：所有第三方action、所有CI工具镜像。标签是可变的，SHA是不可变的。tj-actions、reviewdog和Trivy的安全事件证明这是不可妥协的要求。
  • 密钥不可泄露：永远不要打印、输出到制品、或作为CLI参数传递密钥。永远不要在不受保护的分支上使用受保护变量。
  • 测试流水线本身：使用
    act
    （GitHub Actions本地runner）、
    gitlab-ci-local
    或试运行模式，不要等到生产环境才发现流水线bug。
  • 缓存≠制品：缓存是临时的速度优化手段，制品是可靠的任务间数据传递方式。混淆两者会导致间歇性故障。
  • 生产环境必须手动审批：没有例外。自动部署到staging是合理的，自动部署到生产是事故根源。
  • 扫描前置，部署后置：安全扫描在流水线最早阶段执行，部署在最后阶段执行。部署后才发现CVE的成本极高。
  • PCI-DSS 4.0是强制要求：如果流水线涉及CDE（持卡人数据环境），SBOM生成、制品签名、部署门控都是必选项。