使用 catthehacker/ubuntu Docker 镜像部署 GitHub Actions 本地运行环境

使用 catthehacker/ubuntu Docker 镜像部署 GitHub Actions 本地运行环境

catthehacker/ubuntu 是专为在本地运行 GitHub Actions 工作流而优化的 Docker 镜像。以下是完整的部署和使用指南：

核心镜像版本

完整部署流程

1. 拉取镜像

docker pull catthehacker/ubuntu:act-latest

※：pull不好用的情况下，需要进行docker源的更换：docker永久更换源

2. 创建别名简化命令

echo "alias myact='docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v \"\$(pwd)\":/tmp \
  -w /tmp \
  -e ACT_PULL_NEVER=true \
  -e ACT_ALLOW_NONGIT=1 \
  catthehacker/ubuntu:act-latest \
  act -P ubuntu-latest=catthehacker/ubuntu:act-latest'" >> ~/.bashrc

source ~/.bashrc

3. 验证安装

myact --version
# 输出: act version 0.2.50

使用示例

基本使用

# 在项目目录运行所有工作流
cd your-repo
myact

# 运行特定工作流
myact -W .github/workflows/ci.yml

# 运行特定任务
myact -j build

创建测试项目

mkdir act-demo && cd act-demo
mkdir -p .github/workflows

# 创建简单工作流
cat << 'EOF' > .github/workflows/demo.yml
name: CI Demo
on: [push]
jobs:
  hello:
    runs-on: ubuntu-latest
    steps:
      - name: Greeting
        run: echo "Hello from catthehacker/ubuntu!"
EOF

# 运行测试
myact

高级配置

永久配置文件

mkdir -p ~/.config/act
cat << 'EOF' > ~/.config/act/actrc
# 禁用镜像拉取
ACT_PULL_NEVER=true

# 允许非Git环境
ACT_ALLOW_NONGIT=1

# 设置默认平台
--container-architecture linux/amd64

# 预定义运行器
-P ubuntu-latest=catthehacker/ubuntu:act-latest
-P ubuntu-20.04=catthehacker/ubuntu:act-20.04
EOF

使用配置文件运行

alias myact='docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd)":/workspace \
  -v $HOME/.config/act:/root/.config/act \
  catthehacker/ubuntu:act-latest \
  act'

典型工作流示例

1. Node.js 项目构建

name: Node.js CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm run build
      - run: npm test

2. Python 项目测试

name: Python CI
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Run tests
        run: pytest

3. Docker 镜像构建

name: Docker Build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build Docker image
        run: |
          docker build -t myapp:${{ github.sha }} .
          docker run myapp:${{ github.sha }} --version

性能优化技巧

1. 减少启动时间

# 预先拉取基础镜像
docker pull node:18-alpine
docker pull python:3.10-slim

# 使用缓存目录
docker run ... -v /tmp/act-cache:/var/cache/act ...

2. 资源限制

# 限制容器资源
docker run --rm \
  --cpus=2 \
  --memory=4g \
  ... \
  catthehacker/ubuntu:act-latest \
  act

3. 离线模式

# 保存常用镜像
docker save -o act-images.tar \
  catthehacker/ubuntu:act-latest \
  node:18-alpine \
  alpine:3.16

# 离线加载
docker load -i act-images.tar

常见问题解决

问题1: 权限错误

# 添加特权模式
alias myact='docker run --rm --privileged ...'

问题2: Windows 路径问题

# PowerShell 函数
function Run-Act {
    docker run --rm `
        -v /var/run/docker.sock:/var/run/docker.sock `
        -v ${PWD}:/workspace `
        -w /workspace `
        catthehacker/ubuntu:act-latest `
        act $args
}

问题3: macOS ARM 架构支持

# 指定平台
docker run --rm --platform linux/amd64 ...

镜像定制开发

Dockerfile 示例

FROM catthehacker/ubuntu:act-latest

# 添加自定义工具
RUN apt update && apt install -y \
    jq \
    awscli \
    terraform

# 设置默认工作目录
WORKDIR /workspace

# 添加自定义入口点
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

entrypoint.sh

#!/bin/bash

# 加载自定义配置
if [ -f /workspace/.actrc ]; then
    cp /workspace/.actrc /root/.config/act/actrc
fi

# 执行 act
exec act "$@"

最佳实践总结

1. 镜像选择：

   • 常规使用：catthehacker/ubuntu:act-latest
   • 需要完整工具链：catthehacker/ubuntu:full-latest
   • Node.js 项目：catthehacker/ubuntu:node-16

2. 持久化配置：

   -v $HOME/.config/act:/root/.config/act
   

3. 网络优化：

   # 使用国内镜像源
   docker run ... -e PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple ...
   

4. 定期更新：

   # 每周更新镜像
   (crontab -l; echo "0 3 * * 1 docker pull catthehacker/ubuntu:act-latest") | crontab -
   

5. 安全扫描：

   docker scan catthehacker/ubuntu:act-latest
   

通过以上部署方案，您可以充分利用 catthehacker/ubuntu Docker 镜像在本地高效运行 GitHub Actions 工作流，显著提升开发和测试效率。