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：确认平台

Signal	Platform
`.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

Lint first -- fastest feedback, catches formatting/syntax early
Test -- unit tests, typechecking
Build -- compile, bundle, create artifacts
Scan -- SAST, dependency audit, container scan (on build output)
Deploy -- staging auto, production manual

lint -> test -> build -> scan -> deploy

语法检查优先——最快的反馈，可提前发现格式/语法问题
测试——单元测试、类型检查
构建——编译、打包、生成制品
扫描——SAST、依赖审计、容器扫描（针对构建输出）
部署—— staging环境自动部署，生产环境手动部署

Caching strategy

缓存策略

What	Cache key	Platform 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 layers	BuildKit cache mount or registry cache	GH: `--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

密钥管理

Platform	Mechanism	Scope control
GitHub	Repository/org/environment secrets	Per-environment, per-repo, per-org. Deployment branches.
GitLab	CI/CD variables (project/group/instance)	Protected branches/tags, environments, masked in logs.
Forgejo	Repository/org secrets	Per-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	仓库/组织/环境密钥	按环境、按仓库、按组织配置，支持部署分支限制。
GitLab	CI/CD变量（项目/组/实例级别）	受保护分支/标签、环境限制，日志自动掩码。
Forgejo	仓库/组织密钥	按仓库、按组织配置，暂不支持环境级作用域。

所有平台通用规则：永远不要打印密钥、不要将密钥作为CLI参数传递（可在

ps

中被看到）、不要写入制品，使用环境变量或文件注入方式传递。

Deployment gates

部署门控

Environment	Trigger	Approval
Dev/Preview	Every PR/MR push	None
Staging	Merge to main	None (auto-deploy)
Production	Tag or manual dispatch	Required 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

共享库变更检测

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:

Per-service workflows with
```
paths:
```
filters (simplest, recommended)
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.

仅构建变更的内容，有两种实现方式：

按服务拆分工作流搭配
```
paths:
```
过滤器（最简单，推荐）
单工作流加矩阵+变更检测任务，输出需要构建的服务列表

规则：共享库变更时必须重建所有服务，遗漏共享依赖变更的「无变更跳过」优化比重建所有服务的危害更大。

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的核心差异

Feature	GitHub Actions	Forgejo Actions
`permissions:`	Controls GITHUB_TOKEN scope	Not enforced -- token always has full rw (read-only for fork PRs)
`continue-on-error:` (job level)	Allows job failure without failing workflow	Not supported -- step-level only
Runner images	Managed `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-on	Supported	Supported since v14.0
LXC execution	Not supported	Supported (Forgejo-specific)

功能	GitHub Actions	Forgejo 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 Req	What it means for CI/CD	Implementation
6.2.1	Secure development training + OWASP-aware processes	SAST on every PR/MR, dependency scanning, secret detection
6.2.4	Access control + change tracking	Branch protection, required reviewers, signed commits, audit logs
6.3.2	Software inventory (SBOM)	Generate SPDX/CycloneDX SBOM per release, attach to artifacts
6.4.2	Changes approved, documented, tested	Gated deployments, required approvals for prod, IaC audit trails
6.5.3	Consistent security controls across environments	Same 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

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生成、制品签名、部署门控都是必选项。

ci-cd

Original

Translation

CI/CD Pipelines: Multi-Platform Production Infrastructure

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

When to use

适用场景

When NOT to use

不适用场景

AI Self-Check

AI自检清单

Workflow

工作流

Step 1: Identify the platform

步骤1：确认平台

Step 2: Determine the domain

步骤2：确定领域

Step 3: Gather requirements

步骤3：收集需求

Step 4: Apply platform-specific patterns

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

Step 5: Verify against AI Self-Check

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

Cross-Platform Patterns

跨平台通用模式

Stage ordering (all platforms)

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

Caching strategy

缓存策略

Secret management

密钥管理

Deployment gates

部署门控

Monorepo Patterns

Monorepo适配模式

Path-based triggering

基于路径的触发

Shared library detection

共享库变更检测

Selective builds

选择性构建

Forgejo CI/CD

Forgejo CI/CD

Key differences from GitHub Actions

与GitHub Actions的核心差异

Forgejo workflow template

Forgejo工作流模板

Forgejo-specific gotchas

Forgejo专属注意事项

Forgejo release workflow pattern

Forgejo发布工作流模式

PCI-DSS 4.0: CI/CD Compliance Mapping

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

AI-Age Considerations

AI时代注意事项

Template Conventions

模板约定

Reference Files

参考文档

Related Skills

相关技能

Rules

规则