Gitea Runner执行actions/checkout@v4时无法解析Gitea主机问题排查

核心问题 #

你遇到的域名解析失败，是因为Gitea Action Runner执行工作流时会创建独立的子容器，而这些子容器默认不会加入你配置的gitea_network网桥——它们用的是宿主机的默认Docker网络，自然找不到gitea这个容器名对应的服务。

解决方案 #

方法1：让工作流子容器自动加入gitea_network（推荐）

在Runner的docker-compose配置里添加环境变量ACT_RUNNER_DOCKER_NETWORK=gitea_network，强制runner创建的所有工作流子容器加入指定网络，这样就能直接解析gitea容器名了。修改后的配置如下：

services:
  runner:
    image: gitea/act_runner
    environment:
      GITEA_INSTANCE_URL: "http://gitea:3000"
      GITEA_RUNNER_REGISTRATION_TOKEN: "xxxxxxx"
      GITEA_RUNNER_NAME: "Gitea Runner"
      ACT_RUNNER_DOCKER_NETWORK: "gitea_network"  # 新增这一行
    volumes:
      - ./gitea_runner:/data
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - gitea_network

networks:
  gitea_network:
    driver: bridge
    external: true

方法2：用宿主机IP/域名替代容器名

如果不想修改网络配置，也可以把GITEA_INSTANCE_URL改成宿主机的实际IP或域名（比如http://192.168.1.100:3000），让工作流子容器通过宿主机端口访问Gitea。不过这种方法依赖宿主机IP的稳定性，不如第一种优雅。

补充说明 #

Gitea Action Runner是通过挂载宿主机/var/run/docker.sock实现"docker-in-docker"的，每个CI任务都会启动独立的子容器执行。默认情况下这些子容器不属于你为Gitea和Runner配置的专用网络，所以无法识别容器间的主机名。添加ACT_RUNNER_DOCKER_NETWORK环境变量后，runner会自动将所有工作流子容器加入指定网络，实现容器间的域名互通。

内容的提问来源于stack exchange，提问作者Kobi O