Github Actions执行docker run报错：本地无法找到'docker-repository:latest'镜像

问题场景 #

在使用Github Actions自托管（self-hosted）Runner执行docker run操作时，出现找不到本地镜像的报错，相关部署步骤配置如下：

deploy:
  needs: build
  runs-on: self-hosted
  steps:
    .
    .
    .

    - name: Run Docker Container
      run: sudo docker run -d -p 3002:3002 --name ${{ env.DOCKER_CONTAINER_NAME }} ${{ env.DOCKER_REGISTRY_URL }}

解决方法 #

1. 先拉取镜像再运行 #

自托管Runner本地没有目标镜像时，需要先从镜像仓库拉取。在Run Docker Container步骤前添加拉取命令：

- name: Pull Docker Image
  run: sudo docker pull ${{ env.DOCKER_REGISTRY_URL }}

如果是私有镜像仓库，还要先完成登录操作：

- name: Login to Docker Registry
  run: sudo docker login ${{ env.DOCKER_REGISTRY_URL }} -u ${{ secrets.DOCKER_USERNAME }} -p ${{ secrets.DOCKER_PASSWORD }}

2. 检查环境变量正确性 #

确认${{ env.DOCKER_REGISTRY_URL }}变量值为完整的镜像名（如docker-repository:latest），无拼写错误。可以添加步骤打印变量排查：

- name: Verify Docker Image Name
  run: echo "Target image: ${{ env.DOCKER_REGISTRY_URL }}"

3. 解决sudo权限导致的镜像上下文问题 #

sudo会使用root用户的Docker上下文，可能和构建镜像时的用户上下文不一致，导致找不到镜像：

• 给Runner用户添加Docker组权限，后续无需使用sudo：

  sudo usermod -aG docker $USER
  

  执行命令后重启自托管Runner服务
• 或者确保构建镜像的步骤也使用sudo执行，保证镜像存储在root用户的镜像库中

4. 验证Runner本地镜像列表 #

添加步骤查看Runner上已有的镜像，确认目标镜像是否存在：

- name: List Local Docker Images
  run: sudo docker images

内容的提问来源于stack exchange，提问作者Shubham Verma