Deploying a Docker image to a remote private registry with Gitlab CI
By Mike Street
I am a huge fan of Gitlab. What you are able to get on the free tier is incredible (although I do wish their Premium tier was slightly cheaper, but I digress) and the processes and optimisations it unlocks is infinite. The CI/Pipelines are such a powerful tool (but are by no means easy to get started with). The world of Gitlab CI is mind boggling, the syntax is confusing and debugging is near impossible, however every now and then you get it right and tingle of success flutters through you.
Hopefully, this post will help someone get to the completion point sooner, as it took me a lot of Googling and fake commits and getting things wrong before I got it right. I am fortunate to have my Gitlab runners self-hosted otherwise I would have quickly burnt through the 400 free minutes.
The scenario is this: We wanted our Gitlab CI to build our application, package it up in a Docker image and push that image to a private registry (which would then deploy to "the cloud").
The first step is to set up the variables which will be used during the process. It's good practice to use variables instead of committing your usernames and passwords directly in the
In the repository on Gitlab, navigate to Settings -> CI/CD -> Variables and add the following (feel free to change the variable names, don't forget to update the YAML)
DOCKER_REGISTRY_PASS- The password to the private registry
DOCKER_REGISTRY_USER- The username for the private registry
DOCKER_REGISTRY- The URL to the registry (without any protocol - e.g.
Before proceeding, make sure the image you are using has the Docker process available. If you are using a custom image, this can be added by using the script from
# Docker RUN curl -fsSL https://get.docker.com -o get-docker.sh RUN sh get-docker.sh
Next, create your (or edit) your
.gitlab-ci.yml and add a build stage.
push_image: stage: - deploy before_script: - echo "$DOCKER_REGISTRY_PASS" | docker login $DOCKER_REGISTRY --username $DOCKER_REGISTRY_USER --password-stdin script: - composer install --no-ansi --no-dev --no-interaction --no-scripts --no-progress --optimize-autoloader - npm i - npm run build - docker build -t $PRODUCTION_DOCKER_REGISTRY/production-image-name:$CI_PIPELINE_IID . - docker push $PRODUCTION_DOCKER_REGISTRY/production-image-name:$CI_PIPELINE_IID only: - main
The example above has
npm install stages, should you need them. The
only key is for the branch on which the task runs. The
$CI_PIPELINE_IID is a predefined variable from Gitlab - it allows you to re-run the pipeline and overwrite the same image. It also ties it to the pipeline, not the date or time or any other variable of which you could accidentally generate a duplicate. It also allows you to republish previous pipelines if something goes amiss.
Our pipelines feature an extra step - which is to build the image and push it to the Gitlab instance before pulling this image and pushing it elsewhere. This means if the pipeline fails or if you need to redeploy the same image, you don't have to rebuild all the assets. It means if the pipeline fails upon deployment, you still have the image locally to re-push it.
image_build step looks like the above, except the
DOCKER credentials for the Gitlab registry. The image build step also had the push location updated to use the current repositories Docker registry:
script: - docker build -t $CI_REGISTRY_IMAGE:$CI_PIPELINE_IID . - docker push $CI_REGISTRY_IMAGE:$CI_PIPELINE_IID
We then have a second step which pulls from Gitlab and pushes to the remote registry:
.deploy: image: registry.gitlab.lldev.co.uk/devops/containers/development:bullseye-php7.4-composer2-node14 allow_failure: false variables: GIT_STRATEGY: none before_script: - export VERSION=$(date +"%Y%m%d-%H%M") # Login to our registry - echo "$DOCKER_REGISTRY_PASS" | docker login $DOCKER_REGISTRY --username $DOCKER_REGISTRY_USER --password-stdin # Login to their registry - echo "$PRODUCTION_DOCKER_REGISTRY_PASS" | docker login $PRODUCTION_DOCKER_REGISTRY --username $PRODUCTION_DOCKER_REGISTRY_USER --password-stdin script: # Pull from our registry - docker pull $CI_REGISTRY_IMAGE:$CI_PIPELINE_IID # Re-tag - docker tag $CI_REGISTRY_IMAGE:$CI_PIPELINE_IID $PRODUCTION_DOCKER_REGISTRY/production-image-name:$CI_PIPELINE_IID - docker push $PRODUCTION_DOCKER_REGISTRY/production-image-name:$CI_PIPELINE_IID