使用 catthehacker/ubuntu Docker 镜像部署 GitHub Actions 本地运行环境
使用 catthehacker/ubuntu Docker 镜像部署 GitHub Actions 本地运行环境
catthehacker/ubuntu 是专为在本地运行 GitHub Actions 工作流而优化的 Docker 镜像。以下是完整的部署和使用指南：
核心镜像版本
| 镜像名称 | 描述 | 大小 |
|---|---|---|
catthehacker/ubuntu:act-latest | 最新版 GitHub Actions 运行器 | ~1.2GB |
catthehacker/ubuntu:full-latest | 包含完整工具的版本 | ~3.5GB |
catthehacker/ubuntu:node-16 | 预装 Node.js 16 的版本 | ~1.8GB |
完整部署流程
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'" >> ~/.bashrcsource ~/.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-lateststeps:- name: Greetingrun: 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-lateststeps:- uses: actions/checkout@v4- name: Use Node.jsuses: actions/setup-node@v3with: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-lateststeps:- uses: actions/checkout@v4- name: Set up Pythonuses: actions/setup-python@v4with:python-version: '3.10'- name: Install dependenciesrun: pip install -r requirements.txt- name: Run testsrun: pytest
3. Docker 镜像构建
name: Docker Build
on: [push]
jobs:build:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- name: Build Docker imagerun: |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 ]; thencp /workspace/.actrc /root/.config/act/actrc
fi# 执行 act
exec act "$@"
最佳实践总结
-
镜像选择：
- 常规使用：
catthehacker/ubuntu:act-latest - 需要完整工具链：
catthehacker/ubuntu:full-latest - Node.js 项目：
catthehacker/ubuntu:node-16
- 常规使用：
-
持久化配置：
-v $HOME/.config/act:/root/.config/act -
网络优化：
# 使用国内镜像源 docker run ... -e PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple ... -
定期更新：
# 每周更新镜像 (crontab -l; echo "0 3 * * 1 docker pull catthehacker/ubuntu:act-latest") | crontab - -
安全扫描：
docker scan catthehacker/ubuntu:act-latest
通过以上部署方案，您可以充分利用 catthehacker/ubuntu Docker 镜像在本地高效运行 GitHub Actions 工作流，显著提升开发和测试效率。