{"id":49532,"date":"2025-05-28T03:30:32","date_gmt":"2025-05-28T03:30:32","guid":{"rendered":"https:\/\/www.devopsschool.com\/blog\/?p=49532"},"modified":"2025-05-28T03:32:13","modified_gmt":"2025-05-28T03:32:13","slug":"gitlab-deploy-container-registry-a-complete-guide","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/blog\/gitlab-deploy-container-registry-a-complete-guide\/","title":{"rendered":"GitLab Deploy – Container Registry – A Complete Guide"},"content":{"rendered":"\n

Here’s a complete step-by-step guide<\/strong> for:<\/p>\n\n\n\n

\u2705 Building a Docker image<\/strong>
\u2705 Storing (pushing) it to GitLab’s Container Registry<\/strong>
\u2705 Using GitLab CI\/CD pipeline<\/strong> with GitLab SaaS 18.x<\/strong><\/p>\n\n\n\n

\n\n\n\n

\ud83d\ude80 Use Case<\/h2>\n\n\n\n

You want to:<\/p>\n\n\n\n

    \n
  • Build a Docker image from your code<\/li>\n\n\n\n
  • Push it to GitLab\u2019s Container Registry<\/strong><\/li>\n\n\n\n
  • Use it later for deployment or as base image<\/li>\n<\/ul>\n\n\n\n
    \n\n\n\n

    \ud83e\uddf1 Prerequisites<\/h2>\n\n\n\n
      \n
    • A GitLab project on GitLab.com (SaaS)<\/li>\n\n\n\n
    • GitLab CI\/CD enabled<\/li>\n\n\n\n
    • .gitlab-ci.yml<\/code> file created<\/li>\n\n\n\n
    • Dockerfile at the root of your project<\/li>\n<\/ul>\n\n\n\n
      \n\n\n\n

      \ud83d\udcdd Step 1: Create a Dockerfile<\/code><\/h2>\n\n\n\n

      Here\u2019s an example Dockerfile<\/code> for a Java app:<\/p>\n\n\n

      # syntax=docker\/dockerfile:1<\/span>\nFROM openjdk:17<\/span>-jdk-slim\nCOPY .\/target\/myapp.jar \/app\/myapp.jar\nCMD [\"java\"<\/span>, \"-jar\"<\/span>, \"\/app\/myapp.jar\"<\/span>]\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
      Make sure your JAR is built to .\/target\/myapp.jar<\/code> via Maven or Gradle.<\/p>\n\n\n\n
      \n\n\n\n
      \ud83d\udce6 Step 2: Understand Your GitLab Container Registry URL<\/h2>\n\n\n\n
      GitLab automatically enables a private container registry for every project:<\/p>\n\n\n
      registry.gitlab.com\/<namespace<\/span>><\/span>\/<project<\/span>><\/span>\n<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
      \ud83d\udccc Example:<\/p>\n\n\n
      registry.gitlab.com\/yourusername\/myapp\n<\/code><\/span><\/pre>\n\n\n
      You can view it in:
      Project \u2192 Deploy \u2192 Container Registry<\/strong><\/p>\n\n\n\n
        \n
      • \u2705 <namespace><\/code> can be:\n
          \n
        • A personal username<\/strong> (yourusername<\/code>)<\/li>\n\n\n\n
        • A GitLab group<\/strong> (yourgroup<\/code>)<\/li>\n\n\n\n
        • A GitLab subgroup path<\/strong> (yourgroup\/subgroup<\/code>)<\/li>\n<\/ul>\n<\/li>\n\n\n\n
        • \u2705 <project><\/code> is always the project name<\/strong><\/li>\n<\/ul>\n\n\n\n
          \n\n\n\n
          \u2699\ufe0f Step 3: Configure .gitlab-ci.yml<\/code><\/h2>\n\n\n\n
          Here\u2019s a full working example:<\/p>\n\n\n
          stages:\n  - build\n  - dockerize\n  - push\n\nvariables:\n  IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA\n\n# Build your app (optional if using compiled files)<\/span>\nbuild-job:\n  stage: build\n  image: maven:3.8<\/span>.7<\/span>-openjdk-17<\/span>\n  script:\n    - mvn clean package -DskipTests\n\ndockerize-job:\n  stage: dockerize\n  image: docker:latest\n  services:\n    - docker:dind\n  before_script:\n    - echo<\/span> $CI_JOB_TOKEN | docker login -u gitlab-ci-token --password-stdin $CI_REGISTRY\n  script:\n    - docker build -t $IMAGE_TAG .\n    - docker push $IMAGE_TAG\n  only:\n    - main\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
          \n\n\n\n
          \ud83e\udde0 Explanation of Important Variables<\/h2>\n\n\n\n
          Variable<\/th>Purpose<\/th><\/tr><\/thead>
          $CI_REGISTRY<\/code><\/td>Points to registry.gitlab.com<\/code><\/td><\/tr>
          $CI_REGISTRY_IMAGE<\/code><\/td>Your project-specific Docker registry path<\/td><\/tr>
          $CI_JOB_TOKEN<\/code><\/td>GitLab\u2019s built-in token for authenticating CI jobs<\/td><\/tr>
          gitlab-ci-token<\/code><\/td>Required user for registry auth inside CI\/CD<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
          \n\n\n\n
          \ud83d\udd10 Step 4: CI\/CD Authentication<\/h2>\n\n\n\n
          GitLab uses:<\/p>\n\n\n\n
            \n
          • Username:<\/strong> gitlab-ci-token<\/code><\/li>\n\n\n\n
          • Password:<\/strong> $CI_JOB_TOKEN<\/code><\/li>\n<\/ul>\n\n\n\n
            Docker login is done via:<\/p>\n\n\n
            echo<\/span> $CI_JOB_TOKEN | docker login -u gitlab-ci-token --password-stdin $CI_REGISTRY\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
            \n\n\n\n
            \ud83d\udd0d Step 5: View Container in Registry<\/h2>\n\n\n\n
            After pushing:<\/p>\n\n\n\n
              \n
            1. Go to your GitLab project<\/li>\n\n\n\n
            2. Navigate to Deploy > Container Registry<\/strong><\/li>\n\n\n\n
            3. You’ll see the image like: registry.gitlab.com\/yourusername\/myapp:abcdef1<\/code><\/li>\n<\/ol>\n\n\n\n
              \n\n\n\n
              \ud83d\udee0\ufe0f Step 6: Pull and Use the Image Anywhere<\/h2>\n\n\n\n
              From any machine (with Docker installed):<\/p>\n\n\n
              docker login registry.gitlab.com\ndocker pull registry.gitlab.com\/yourusername\/myapp:<tag<\/span>><\/span>\n<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
              \n\n\n\n
              \ud83d\udd01 Optional: Use latest<\/code> Tag and Versioning<\/h2>\n\n\n
              variables:\n  IMAGE_TAG: $CI_REGISTRY_IMAGE:latest\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
              Or for versioning:<\/p>\n\n\n
              IMAGE_TAG: $CI_REGISTRY_IMAGE:${CI_COMMIT_REF_NAME\/\/\\\/\/-}<\/span>\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
              \n\n\n\n
              \u2705 Summary<\/h2>\n\n\n\n
              Step<\/th>Description<\/th><\/tr><\/thead>
              1<\/td>Write a Dockerfile<\/code><\/td><\/tr>
              2<\/td>Identify your GitLab container registry path<\/td><\/tr>
              3<\/td>Configure .gitlab-ci.yml<\/code> to build & push<\/td><\/tr>
              4<\/td>Use docker login<\/code> with CI_JOB_TOKEN<\/code><\/td><\/tr>
              5<\/td>View in Deploy \u2192 Container Registry<\/strong><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
              \n\n\n\n
              Great observation! The line:<\/p>\n\n\n
              services<\/span>:\n  -<\/span> docker<\/span>:dind<\/span>\n<\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
              is critical<\/strong> when using Docker inside GitLab CI\/CD pipelines<\/strong> \u2014 especially when building or pushing Docker images.<\/p>\n\n\n\n
              \n\n\n\n
              \ud83d\udd0d What is docker:dind<\/code>?<\/h2>\n\n\n\n
                \n
              • **dind**<\/code> stands for Docker-in-Docker<\/strong>.<\/li>\n\n\n\n
              • docker:dind<\/code> is a Docker image that runs the Docker daemon<\/strong> as a background service inside your CI\/CD job.<\/li>\n\n\n\n
              • This allows the main job container<\/strong> to use Docker commands (docker build<\/code>, docker push<\/code>, etc.), even though it’s running in an isolated environment.<\/li>\n<\/ul>\n\n\n\n
                \n\n\n\n
                \ud83d\udd27 Why is It Needed?<\/h2>\n\n\n\n
                GitLab CI\/CD runs your job steps inside a container<\/strong> (e.g., docker:latest<\/code>), which doesn’t have the Docker daemon running by default<\/strong>.<\/p>\n\n\n\n
                So you need to add:<\/p>\n\n\n
                services<\/span>:\n  -<\/span> docker<\/span>:dind<\/span>\n<\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
                This launches a background Docker daemon, which your main container can talk to (usually via the socket on localhost<\/code> or Docker host networking).<\/p>\n\n\n\n
                \n\n\n\n
                \ud83e\uddea Example Use in Context<\/h2>\n\n\n
                dockerize-job:\n  stage: dockerize\n  image: docker:latest        # Main container with Docker CLI<\/span>\n  services:\n    - docker:dind             # Side container with Docker daemon<\/span>\n  script:\n    - docker build -t $IMAGE_TAG .\n    - docker push $IMAGE_TAG\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                  \n
                • docker:latest<\/code><\/strong> \u2192 contains the Docker CLI<\/li>\n\n\n\n
                • docker:dind<\/code><\/strong> \u2192 provides the Docker daemon to execute docker<\/code> commands<\/li>\n<\/ul>\n\n\n\n
                  \n\n\n\n
                  \ud83d\udd10 Important: Secure Docker-in-Docker<\/h2>\n\n\n\n
                  For security and performance:<\/p>\n\n\n\n
                    \n
                  • GitLab runs Docker-in-Docker in privileged mode<\/strong> automatically when using their Docker executor.<\/li>\n\n\n\n
                  • You may explicitly add (if self-hosted):<\/li>\n<\/ul>\n\n\n
                      tags:\n    - docker\n  variables<\/span>:\n    DOCKER_TLS_CERTDIR: \"\"<\/span>\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
                    This disables TLS cert enforcement (GitLab-specific tweak for dind<\/code>).<\/p>\n\n\n\n
                    \n\n\n\n
                    \u26a0\ufe0f Alternatives to docker:dind<\/code><\/h2>\n\n\n\n
                      \n
                    • Kaniko<\/strong>: A rootless, safer Docker image builder (good for Kubernetes-based runners)<\/li>\n\n\n\n
                    • Buildah + Podman<\/strong>: For more secure container builds without daemon<\/li>\n\n\n\n
                    • GitLab CI with remote Docker host<\/strong><\/li>\n<\/ul>\n\n\n\n
                      \n\n\n\n
                      \u2705 Summary<\/h2>\n\n\n\n
                      docker:dind<\/code><\/th>Explanation<\/th><\/tr><\/thead>
                      Docker-in-Docker<\/td>Runs Docker daemon inside CI\/CD service<\/td><\/tr>
                      Required for<\/td>docker build<\/code>, docker push<\/code>, etc. in pipeline<\/td><\/tr>
                      Used alongside<\/td>Docker CLI image (docker:latest<\/code>)<\/td><\/tr>
                      Daemon runs in<\/td>Background, accessible to main job container<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                      \n\n\n\n
                      <\/p>\n","protected":false},"excerpt":{"rendered":"
                      Here’s a complete step-by-step guide for: \u2705 Building a Docker image\u2705 Storing (pushing) it to GitLab’s Container Registry\u2705 Using GitLab CI\/CD pipeline with GitLab SaaS 18.x \ud83d\ude80 Use Case You… <\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"_joinchat":[],"footnotes":""},"categories":[2],"tags":[],"class_list":["post-49532","post","type-post","status-publish","format-standard","hentry","category-uncategorised"],"_links":{"self":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/49532","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/comments?post=49532"}],"version-history":[{"count":2,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/49532\/revisions"}],"predecessor-version":[{"id":49534,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/49532\/revisions\/49534"}],"wp:attachment":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/media?parent=49532"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/categories?post=49532"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/tags?post=49532"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}