Docker-GitHub-Actions 实验性镜像文档

一、镜像概述

1.1 镜像简介

本镜像为实验性 Docker 镜像，旨在为支持 Docker 的 GitHub Actions 工作流提供核心功能支持。其主要用途是在 GitHub Actions 环境中集成 Docker 相关操作能力，简化 CI/CD 流程中 Docker 镜像构建、推送、运行等任务的配置与执行。

二、核心功能与特性

2.1 主要功能

• 提供与 GitHub Actions Runner 的环境集成能力，支持在工作流中直接调用 Docker 命令
• 内置 Docker 引擎运行时，可直接执行 docker build、docker push、docker run 等核心操作
• 支持 GitHub Actions 工作流任务编排，可与其他 Actions 步骤联动（如代码拉取、测试结果上报等）

2.2 特性

• 轻量级设计：基于精简基础镜像，减少工作流执行时的资源占用
• 实验性特性：包含针对 Docker-GitHub Actions 集成的前沿功能（可能涉及未稳定 API）
• 环境隔离：通过容器化方式隔离 Docker 操作环境，避免影响 GitHub Actions Runner 主机环境

三、使用场景与适用范围

3.1 适用场景

• CI/CD 流程集成：在 GitHub Actions 工作流中实现 Docker 镜像的自动化构建、测试与推送
• Docker 操作测试：开发人员验证 Docker 命令在 GitHub Actions 环境中的执行效果
• 工作流定制：通过自定义 Docker 任务扩展 GitHub Actions 能力，满足特定业务需求

3.2 适用范围

• 运行环境：GitHub Actions 官方 Runner（Linux/Windows/macOS）或自托管 Runner（需支持 Docker 引擎）
• 依赖条件：需配置 GitHub Actions 工作流权限（如 contents: read、packages: write）及 Docker registry 访问凭证

四、使用方法与配置说明

4.1 环境变量

4.2 基本使用（本地测试）

通过 docker run 命令可本地测试镜像功能（模拟 GitHub Actions 环境）：

docker run -it --rm \
  -e GITHUB_TOKEN="your_github_token" \
  -e DOCKER_REGISTRY="docker.io" \
  -e DOCKER_USERNAME="your_docker_username" \
  -e DOCKER_PASSWORD="your_docker_password" \
  -v $(pwd):/github/workspace \
  <镜像名称>:<标签> \
  docker build -t $DOCKER_REGISTRY/$DOCKER_USERNAME/test-image:latest /github/workspace

说明：-v $(pwd):/github/workspace 挂载本地目录至容器工作目录，模拟 GitHub Actions 中的代码仓库挂载。

4.3 GitHub Actions 工作流集成

在 GitHub Actions 工作流文件（如 .github/workflows/docker-build.yml）中集成该镜像：

name: Docker Build and Push
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run Docker action via experimental image
        uses: docker://<镜像名称>:<标签>
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          DOCKER_REGISTRY: "ghcr.io"
          DOCKER_USERNAME: ${{ github.actor }}
        with:
          args: docker build -t $DOCKER_REGISTRY/$DOCKER_USERNAME/my-app:${{ github.sha }} .

说明：with.args 用于指定容器内执行的 Docker 命令，示例中为构建镜像并标记为 GitHub 提交 SHA。

五、注意事项

1. 实验性镜像风险：本镜像为实验性版本，功能稳定性未经过长期验证，可能存在 API 变更或功能异常，不建议用于生产环境。
2. 权限配置：需确保 GitHub Actions 工作流具备足够权限（如 packages: write 用于推送镜像至 GitHub Packages）。
3. 版本兼容：Docker 引擎版本需与镜像内置运行时兼容（建议使用 Docker 20.10+）。
4. 资源限制：在自托管 Runner 中使用时，需合理配置容器 CPU/内存资源，避免影响工作流执行效率。