devopsinfra/action-container-structure-test

devopsinfra

这是一个GitHub Action镜像，基于Alpine构建，支持多平台，用于在CI环境中运行Google Container Structure Tests，验证容器镜像的命令、文件、元数据等合规性。

下载次数: 0状态：社区镜像维护者：devopsinfra仓库类型：镜像最近更新：26 天前

让 AI 帮你使用轩辕镜像？ · 展开查看说明

如果你使用 DeepSeek、元宝 AI、Copilot、ChatGPT 等 AI 工具，协助配置轩辕镜像、编写 docker pull 命令、修改 Docker Compose 镜像地址、配置镜像加速、排查镜像拉取失败、分析报错日志等问题，请先让 AI 阅读并遵守轩辕镜像的规则文档。

只需在 AI 对话中先发送下面这段话即可：

请先阅读并遵守：https://xuanyuan.cloud/agents.md

未读文档前不要生成 pull 命令或排错方案。

查看 agents.md 用法指南与完整示范。国内用户首推元宝 AI、DeepSeek 的深度思考模式，不推荐豆包 AI；Cursor 等编辑器可在对话 @ 该链接，或加入 User Rules。若 AI 无法访问外链，可打开说明文档复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。

镜像标签列表与下载命令

🚀 Container Structure Test

用于在CI中运行Google Container Structure Tests的GitHub Action镜像

📦 可用地址

Docker Hub: https://hub.docker.com/repository/docker/devopsinfra/action-container-structure-test
GitHub Packages: https://github.com/devops-infra/action-container-structure-test/pkgs/container/action-container-structure-test

✨ 核心功能

在CI中运行https://github.com/GoogleContainerTools/container-structure-test
支持所有测试类型：命令测试、文件存在性测试、文件内容测试、元数据测试、许可证测试
支持docker、tar和host驱动
执行CST前，从GitHub Actions作业环境渲染测试配置中的{{VAR_NAME}}占位符
将测试总数（总/通过/失败）作为Action输出暴露
多平台镜像：linux/amd64和linux/arm64
轻量级Alpine-based Docker镜像

🔗 相关Action

查看DevOps-Infra的其他Action

📊 徽章

https://github.com/devops-infra/action-container-structure-test "shields.io"
https://hub.docker.com/r/devopsinfra/action-container-structure-test "shields.io"

🏷️ 版本标签：vX, vX.Y, vX.Y.Z

该Action支持三种标签级别以实现灵活版本控制：

vX：主版本的最新补丁（如v1）
vX.Y：次版本的最新补丁（如v1.0）
vX.Y.Z：固定到特定版本（如v1.0.0）

📖 API参考

yaml
    - name: 运行Action
      uses: devops-infra/action-container-structure-test@v1.0.7
      with:
        image: docker.xuanyuan.run/my-image:latest
        config: tests/structure-test.yaml
        driver: docker
        output: text
        debug: false

🔧 输入参数

输入参数	是否必填	默认值	描述
`image`	*		待测试镜像。除非设置`image_from_oci_layout`，否则必填。与后者互斥。
`config`	是		测试配置文件路径。多个文件用空格或换行分隔。`{{VAR_NAME}}`占位符从作业环境渲染。
`driver`	否	`docker`	运行测试时使用的驱动：`docker`、`tar`或`host`。
`platform`	否		测试平台，如`linux/amd64`或`linux/arm64`。默认与主机架构一致。
`pull`	否	`false`	运行测试前强制拉取镜像（仅docker驱动）。
`save`	否	`false`	测试后保留创建的容器。
`quiet`	否	`false`	抑制测试输出。
`no_color`	否	`false`	禁用彩色输出。
`output`	否	`text`	输出格式：`text`、`json`或`junit`。
`test_report`	否		将测试结果写入该文件路径，然后打印到日志。CST自动将`text`转换为`json`。
`junit_suite_name`	否		JUnit测试套件名称（仅当`output`为`junit`时使用）。
`metadata`	否		镜像元数据文件路径。
`runtime`	否		docker驱动使用的运行时（如gVisor的`runsc`）。
`force`	否	`false`	强制运行host驱动，无需交互提示。
`image_from_oci_layout`	否		OCI镜像布局目录路径。与`image`互斥。
`default_image_tag`	否		OCI布局缺少ref注释时的默认镜像标签。需设置`image_from_oci_layout`。
`ignore_ref_annotation`	否	`false`	加载OCI布局时忽略`org.opencontainers.image.ref.name`注释。
`debug`	否	`false`	启用Action入口点的详细调试日志。

📤 输出参数

输出参数	描述
`total`	执行的测试总数。
`passed`	通过的测试数量。
`failed`	失败的测试数量。
`exit_code`	`container-structure-test`返回的退出码。

💻 使用示例

📝 基础示例

使用单个配置文件对Docker镜像运行结构测试。

yaml
name: 每次提交运行结构测试
on: [push]
jobs:
  container-structure-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: 构建镜像
        run: docker build -t my-image:latest .

      - uses: devops-infra/action-container-structure-test@v1
        with:
          image: docker.xuanyuan.run/my-image:latest
          config: tests/structure-test.yaml

🔀 高级示例

使用多个配置文件、JSON输出和保存报告运行测试。

yaml
name: 每次提交运行结构测试
on: [push]
jobs:
  container-structure-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: 构建镜像
        run: docker build -t my-image:latest .

      - name: 运行结构测试
        id: cst
        uses: devops-infra/action-container-structure-test@v1
        with:
          image: docker.xuanyuan.run/my-image:latest
          config: |
            tests/command-tests.yaml
            tests/file-tests.yaml
          output: json
          test_report: /tmp/cst-report.json
          pull: 'false'
          debug: 'false'

      - name: 显示测试结果
        run: |
          echo "Total:  ${{ steps.cst.outputs.total }}"
          echo "Passed: ${{ steps.cst.outputs.passed }}"
          echo "Failed: ${{ steps.cst.outputs.failed }}"
          echo "Exit:   ${{ steps.cst.outputs.exit_code }}"

🎯 使用特定版本

根据稳定性需求选择标签级别：

vX.Y.Z：精确不可变版本（最可预测）
vX.Y：次版本内的最新补丁
vX：主版本内的最新补丁

yaml
name: 每次提交运行结构测试
on: [push]
jobs:
  container-structure-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: devops-infra/action-container-structure-test@v1.0.7
        id: pin-patch-version
        with:
          image: docker.xuanyuan.run/my-image:latest
          config: tests/structure-test.yaml

      - uses: devops-infra/action-container-structure-test@v1.0
        id: pin-minor-version
        with:
          image: docker.xuanyuan.run/my-image:latest
          config: tests/structure-test.yaml

      - uses: devops-infra/action-container-structure-test@v1
        id: pin-major-version
        with:
          image: docker.xuanyuan.run/my-image:latest
          config: tests/structure-test.yaml

🧪 JUnit输出

生成JUnit报告用于测试结果发布。

yaml
name: 每次提交运行结构测试
on: [push]
jobs:
  container-structure-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: 构建镜像
        run: docker build -t my-image:latest .

      - name: 运行结构测试
        uses: devops-infra/action-container-structure-test@v1
        with:
          image: docker.xuanyuan.run/my-image:latest
          config: tests/structure-test.yaml
          output: junit
          junit_suite_name: container-structure-tests
          test_report: /tmp/cst-results.xml

📦 TAR驱动

无需Docker守护进程测试导出的镜像（仅文件/元数据测试）。

yaml
name: 每次提交运行结构测试
on: [push]
jobs:
  container-structure-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: 导出镜像为tar
        run: docker save my-image:latest -o my-image.tar

      - uses: devops-infra/action-container-structure-test@v1
        with:
          image: my-image.tar
          config: tests/file-tests.yaml
          driver: tar

📋 测试配置参考

Container Structure Test配置为YAML或JSON文件。当前 schema版本为2.0.0，必须在每个配置中设置。

Action在调用CST前会渲染配置文件中的{{VAR_NAME}}占位符。用于工作流控制的值（如导出到GITHUB_ENV的版本）可使用此功能。容器内的shell扩展应保留${VAR}语法。

示例：

yaml
commandTests:
  - name: Azure CLI
    command: bash
    args:
      - -lc
      - test "$(az version --output json | jq -r '."azure-cli"')" = '{{AZ_VERSION}}'

yaml
schemaVersion: '2.0.0'

commandTests:
  - name: "python版本"
    command: "python3"
    args: ["--version"]
    expectedOutput: ["Python 3\\..*"]

fileExistenceTests:
  - name: "入口点存在"
    path: "/entrypoint.sh"
    shouldExist: true
    permissions: "-rwxr-xr-x"

fileContentTests:
  - name: "源列表"
    path: "/etc/os-release"
    expectedContents: [".*alpine.*"]

metadataTest:
  workdir: "/app"
  envVars:
    - key: PATH
      value: "/usr/local/bin:.*"
      isRegex: true

完整文档：https://github.com/GoogleContainerTools/container-structure-test

🏗️ CI/CD

包含的工作流：

（自动）创建拉取请求（.github/workflows/auto-pull-request-create.yml）
- 触发条件：推送到除master和dependabot/**外的任何分支
- 作业：
  - 代码检查
  - 构建并推送多平台测试镜像，检查清单
  - 创建拉取请求
（自动）创建版本（.github/workflows/auto-create-release.yml）
- 触发条件：pull_request关闭且推送到release/**（仅从release/合并的PR运行）
- 作业：
  - 代码检查
  - 打标签：创建vX.Y.Z；更新vX.Y和vX（如果远程存在完整标签则失败）
  - 构建并推送多平台镜像，检查清单
  - 发布GitHub Release
  - 更新Docker Hub描述
（定时）每周依赖构建（.github/workflows/cron-dependency-update.yml）
- 触发条件：每周一08:00 UTC
- 作业：
  - 代码检查
  - 构建并推送多平台测试镜像，检查清单
（手动）准备版本分支（.github/workflows/manual-release-branch-prepare.yml）
- 触发条件：手动workflow_dispatch，需提供type（patch|minor|major|set）或type=set时的version
- 创建release/vX.Y.Z，构建/推送-rc镜像，并打开版本PR
- 合并该PR触发.github/workflows/auto-release-create.yml，打标签并发布最终版本
- 作业：
  - 更新版本：升级或设置；输出REL_VERSION

镜像拉取方式

您可以使用以下命令拉取该镜像。请将 <标签> 替换为具体的标签版本。如需查看所有可用标签版本，请访问标签列表页面。

轩辕镜像加速拉取命令点我查看更多 action-container-structure-test 镜像标签

docker pull docker.xuanyuan.run/devopsinfra/action-container-structure-test:<标签>

使用方法：

DockerHub 原生拉取命令

docker pull devopsinfra/action-container-structure-test:<标签>

轩辕镜像配置手册

按平台快速找到配置文档

一键安装

一键安装 Docker

Linux Docker 一键安装

AI

用 AI 使用轩辕镜像

agents.md · AI 对话 · 提示词

Docker

登录仓库拉取

登录认证 · 私有仓库

专属域名拉取

免登录 · 高速拉取

Linux

Docker 镜像配置

Windows / Mac

Docker Desktop 配置

MacOS OrbStack

OrbStack 容器

Apple Container

macOS 原生容器

Docker Compose

Compose 项目配置

NAS

群晖

Synology 配置

飞牛

fnOS 镜像配置

绿联

绿联 NAS

威联通

QNAP 配置

极空间

极空间 NAS

Unraid

Unraid NAS

企业仓库

其他仓库

ghcr · Quay · nvcr

Harbor 镜像源

Proxy Repository 对接

Portainer 镜像源

Registries 配置

Nexus 镜像源

Docker Proxy 缓存

开发工具

Dev Containers

VS Code 开发容器

Podman

Podman 配置指南

Singularity / Apptainer

HPC 科学计算容器

Kubernetes

K8s Containerd

Kubernetes · Containerd

K3s

轻量级集群

面板 / 网络

爱快路由

爱快 4.0 · iKuai 镜像加速

宝塔面板

一键配置镜像源

需要其他帮助？请查看我们的常见问题Docker 镜像访问常见问题解答或提交工单

镜像拉取常见问题

功能

版本功能对比

功能对比 · 版本选择

支持的镜像仓库

Docker Hub · GCR · GHCR

专属域名用法

专属域名 · 开启停用 · 多仓库

新手拉取配置

docker search 限制

专属域名 · Hub 搜索

不支持 push

仅支持 pull · 不支持

拉取速度原因

带宽 · 缓存 · 冷热镜像

错误码

402 与流量用尽

402 · 流量包 · 充值

401 认证失败

401 · docker login

manifest unknown

标签错误 · 镜像不存在

410 Gone 排查

410 · Docker 升级

429 限流

免费版 · 专业版 · 企业版 · 请求频率

其他报错

DNS 超时

DNS 解析 · 网络超时

TLS 证书失败

no matching manifest（架构）

docker.sock / daemon

账号

失败是否计费

manifest · blob · 计费

申请开票（企业 / 个人）

开票 · 发票 · 工单

修改登录密码

网站 · 仓库 · 重置

注销账户

工单 · 数据 · 注销

原理

mirrors 不生效

daemon.json · 重启

去掉域名前缀

docker tag · 重命名

指定架构拉取

ARM64 · AMD64 · 多架构

latest 与「最新」

digest · 版本号 · 标签

查看全部问题→

用户好评

来自真实用户的反馈，见证轩辕镜像的优质服务

oldzhang

运维工程师

Linux服务器

"Docker访问体验非常流畅，大镜像也能快速完成下载。"