CI项目用到submodule问题解决

发表于 2022-07-13 更新于 2026-03-10 分类于个人，技术，笔记本文字数： 6.2k 阅读时长 ≈ 7 分钟

最近在自己尝试写一个FastAPI的项目, 其中用到了Git的Submodules功能和Gitlab的CI功能, 这两个组合就出现了一些坑, 记录一下

Gitlab-CI & Git submodule的组合

项目目录结构

其中utils下的两个package为其他项目, 并添加到了主项目的submodule里面, 本地构建dockerimage不会报错, 使用CI就会报错

.gitlab-ci.yml

# This file is a template, and might need editing before it works on your project.
# To contribute improvements to CI/CD templates, please follow the Development guide at:
# https://docs.gitlab.com/ee/development/cicd/templates.html
# This specific template is located at:
# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Docker.gitlab-ci.yml

# Build a Docker image with CI/CD and push to the GitLab registry.
# Docker-in-Docker documentation: https://docs.gitlab.com/ee/ci/docker/using_docker_build.html
#
# This template uses one generic job with conditional builds
# for the default branch and all other (MR) branches.

docker-build:
  # Use the official docker image.
  image: docker:latest
  stage: build
  services:
    - docker:dind
  # Default branch leaves tag empty (= latest tag)
  # All other branches are tagged with the escaped branch name (commit ref slug)
  script:
    - |
      if [[ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]]; then
        tag=""
        echo "Running on default branch '$CI_DEFAULT_BRANCH': tag = 'latest'"
      else
        tag=":$CI_COMMIT_REF_SLUG"
        echo "Running on branch '$CI_COMMIT_BRANCH': tag = $tag"
      fi
    - docker "$CI_BUILD_ARGS" build --pull -t "$CI_REGISTRY_IMAGE${tag}" .
    - docker "$CI_BUILD_ARGS" push "$CI_REGISTRY_IMAGE${tag}"
  # Run this job in a branch where a Dockerfile exists
  rules:
    - if: $CI_COMMIT_BRANCH
      exists:
        - Dockerfile

👆🏻是我从官方提取的.gitlab-ci.yml文件

Dockerfile

FROM python:3.9-slim
MAINTAINER Rex Chow <879582094@qq.com>

ENV TZ='Asia/Shanghai'
ENV TIME_OUT=20
ENV LOG_LEVEL='info'
ENV CF_ZONE='example.com'

COPY app /app
WORKDIR /app
EXPOSE 80

RUN pip install -i https://pypi.tuna.tsinghua.edu.cn/simple --no-cache-dir -r /app/requirements.txt && \
    rm -rf ~/.cache/pip && \
    mv /app/utils/weather_forcast/SimHei.ttf /usr/local/lib/python3.9/site-packages/matplotlib/mpl-data/fonts/ttf/
CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port 80 --log-level $LOG_LEVEL"]

问题复现

push以后, CI流水线提示报错

定位问题

这个是在我submodule里的一个字体文件, 不应该没有的, 猜测可能由于submodule没拉取导致, 启动一个历史容器查看

果然submodule没有拉取, 文件夹都是空的

解决过程

查了CSDN¹的博客, 发现问题原因, 需要配置ci设置, 修改CI文件

# This file is a template, and might need editing before it works on your project.
# To contribute improvements to CI/CD templates, please follow the Development guide at:
# https://docs.gitlab.com/ee/development/cicd/templates.html
# This specific template is located at:
# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Docker.gitlab-ci.yml

# Build a Docker image with CI/CD and push to the GitLab registry.
# Docker-in-Docker documentation: https://docs.gitlab.com/ee/ci/docker/using_docker_build.html
#
# This template uses one generic job with conditional builds
# for the default branch and all other (MR) branches.

docker-build:
  # Use the official docker image.
  image: docker:latest
  stage: build
  # 这里添加submodule的策略
  variables:
    GIT_SUBMODULE_STRATEGY: normal
  services:
    - docker:dind
  # Default branch leaves tag empty (= latest tag)
  # All other branches are tagged with the escaped branch name (commit ref slug)
  script:
    - |
      if [[ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]]; then
        tag=""
        echo "Running on default branch '$CI_DEFAULT_BRANCH': tag = 'latest'"
      else
        tag=":$CI_COMMIT_REF_SLUG"
        echo "Running on branch '$CI_COMMIT_BRANCH': tag = $tag"
      fi
    - docker "$CI_BUILD_ARGS" build --pull -t "$CI_REGISTRY_IMAGE${tag}" .
    - docker "$CI_BUILD_ARGS" push "$CI_REGISTRY_IMAGE${tag}"
  # Run this job in a branch where a Dockerfile exists
  rules:
    - if: $CI_COMMIT_BRANCH
      exists:
        - Dockerfile

再次执行CI流水线, 仍然提示问题

查阅了Gitlab runner项目的issues² ³, 发现需要配置runner的pre_clone_script

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "Global_Shared_Runner"
  url = "******"
  token = "*******"
  executor = "docker"
  # 这里增加一行
  pre_clone_script = "sed -i 's/dl-cdn.alpinelinux.org/mirrors.tuna.tsinghua.edu.cn/g' /etc/apk/repositories && apk add openssh-client"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.docker]
    tls_verify = false
    image = "apline"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0

👆🏻是我的runner的config.toml, 增加配置后, 再次执行, 提示权限问题

此时参考第一次的博文⁴, 增加Deploy key并修改.gitmodules, 但是我的版本是CE的, 只能使用Project Access Token, 参考官方手册⁵可以分别给各个submodule创建一个

权限设置为Reporter即可, 详细权限可参见: Gitlab permission and role cheat sheet | Rex Chow's Blog

查了很多博客文档⁶, 大体都说通过Project Access Token进行clone操作语句是git clone https://oauth2:<access_token>@gitlab.com/.../xxx.git, 没有一个说明白为什么username是oauth2?

搜索了一下官方文档⁷, 发现了端倪. Gitlab是支持oauth2认证方式和Personal/project/group access tokens方式, 需要通过以下两种方法实现:

传递parameter的方式(全部适用)

1	curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>"

添加到请求头headers(全部适用)

1	curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects"

或使用OAuth兼容类构造请求头

1	curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/projects"

因此, 需要修改原来的.gitmodules文件中项目的地址, 从SSH改为HTTP(S)才能使用, 故此上面修改runner的配置就可以不必修改了.

总结

使用了submodule的git, 想通过Gitlab CI进行自动构建, 需要按照以下步骤操作才能实现:

确认.gitlab-ci.yml相关build的step包含submodule策略

1 2	variables: GIT_SUBMODULE_STRATEGY: normal # 或者 recursive

为每个submodule创建一个Project Access Token, 并修改.gitmodule文件中submodule的URL为以下格式

http(s)://oauth2:<project_access_token>@gitlab.com/.../xxx.git
重试流水线, 此时应该可以顺利部署