This article was converted by SimpRead; the original source is at www.jianshu.com
When using GitLab CI for continuous integration, you need to register a GitLab Runner; registering a GitLab Runner requires specifying an executor. Several types of executors are available:
1
Among these, the shell executor is relatively simple and commonly used—there is abundant documentation available online, so we will not repeat it here. In contrast, the Docker executor is comparatively less frequently used, likely because it requires integration with Docker.
Phenomenon:
Following the official documentation’s example, we specify an image in the .gitlab.yml file to compile and run our project, as shown below:
The intention behind this configuration is to use the local image mytomcat:v1:
as the image for compiling and running our project. However, when initiating continuous integration, the following error occurs:
4
At the start of the pipeline, instead of using the locally existing mytomcat:v1 image, GitLab Runner attempts to pull that image directly from the Docker Hub central registry—which naturally fails, resulting in the error. Why does this happen?
Explanation and Solution
1. Explanation
This behavior stems from the Docker executor’s pull_policy. Unfortunately, the official documentation places this setting rather far down and somewhat inconspicuously—a notable pitfall. Although you follow the official documentation step-by-step, the result is still incorrect—and confusingly so.
You can click through to view it:
6
It becomes immediately clear: if you intend to use a local image, you must explicitly configure the pull_policy. Otherwise, the default setting pull_policy = "always" applies, meaning GitLab Runner will always attempt to pull the image specified by the image keyword from Docker Hub—hence the root cause of this issue.
2. Solution
Configure the pull_policy, then restart GitLab Runner. As illustrated below:
3. Result
7
The pull_policy takes effect, and the local image is successfully used.