|
| 1 | +- # How To Create a GitLab Container-Registry Read Token and Configure DOCKER_AUTH_CONFIG for Private Runner Image |
| 2 | + - ## Overview |
| 3 | + - This guide shows you how to create a GitLab Project Access Token with read_registry scope, securely capture it, build and export a DOCKER_AUTH_CONFIG JSON blob, and configure your GitLab CI/CD pipeline to use private Docker images with a custom runner. |
| 4 | + - For DevOps engineers or project maintainers who need to pull private images in GitLab CI/CD jobs using the Docker executor. |
| 5 | + - ## Prerequisites |
| 6 | + - Maintainer (or Owner) access to your GitLab project |
| 7 | + - Your project uses the Docker Machine (docker+machine) or Docker executor |
| 8 | + - CI_REGISTRY and CI_REGISTRY_USER are set (GitLab provides these automatically) |
| 9 | + - ## Steps |
| 10 | + - 1. Create a Project Access Token |
| 11 | + - Navigate to **Your Project ▸ Settings ▸ Access Tokens** |
| 12 | + - Name your token, e.g. `registry-read-token` |
| 13 | + - Under **Scopes**, check **read_registry** |
| 14 | + - Click **Create project access token** |
| 15 | + - **Copy** the resulting token value and store it securely (you'll only see it once) |
| 16 | + - 2. Securely Read the Token in Zsh |
| 17 | + - Open a terminal on your local machine (or CI runner) and run: |
| 18 | + - ~~~zsh |
| 19 | + read -sr "REGISTRY_TOKEN?Enter your registry read token: " |
| 20 | + echo |
| 21 | + # -s hides input |
| 22 | + # -r prevents backslashes from being interpreted |
| 23 | + # The trailing echo prints a newline |
| 24 | + ~~~ |
| 25 | + - 3. Build and Export DOCKER_AUTH_CONFIG |
| 26 | + - Use your token to create the JSON structure that Docker and GitLab Runner understand: |
| 27 | + - ~~~sh |
| 28 | + AUTH_B64=$(printf '%s:%s' "$CI_REGISTRY_USER" "$REGISTRY_TOKEN" | base64 | tr -d '\n') |
| 29 | + export DOCKER_AUTH_CONFIG=$(printf '{"auths":{"%s":{"auth":"%s"}}}' "$CI_REGISTRY" "$AUTH_B64") |
| 30 | + ~~~ |
| 31 | + - On macOS, base64 wraps lines by default, so pipe through `tr -d '\n'` |
| 32 | + - `$CI_REGISTRY_USER` is typically `gitlab-ci-token` or your project's read-only username |
| 33 | + - 4. Store DOCKER_AUTH_CONFIG in GitLab CI/CD Settings |
| 34 | + - In your project, go to **Settings ▸ CI/CD ▸ Variables** |
| 35 | + - Click **Add variable**: |
| 36 | + - Key: `DOCKER_AUTH_CONFIG` |
| 37 | + - Type: File |
| 38 | + - Value: (paste the JSON you just exported) |
| 39 | + - Check Protected and Masked if desired |
| 40 | + - Save the variable |
| 41 | + - 5. Reference in .gitlab-ci.yml |
| 42 | + - GitLab Runner will automatically pick up `DOCKER_AUTH_CONFIG` and use it when pulling images. In your `.gitlab-ci.yml`, you do NOT need to explicitly docker login—just ensure the variable is available: |
| 43 | + - ~~~yaml |
| 44 | + image: |
| 45 | + name: registry.gitlab.com/your-group/your-private-image:latest |
| 46 | + # (optional) force fresh pull |
| 47 | + pull_policy: always |
| 48 | + variables: |
| 49 | + # If you're overriding, ensure DOCKER_AUTH_CONFIG is inherited |
| 50 | + DOCKER_AUTH_CONFIG: $DOCKER_AUTH_CONFIG |
| 51 | + stages: |
| 52 | + - build |
| 53 | + build-job: |
| 54 | + stage: build |
| 55 | + script: |
| 56 | + - echo "Building with private image..." |
| 57 | + # GitLab Runner uses DOCKER_AUTH_CONFIG to authenticate automatically |
| 58 | + - docker info |
| 59 | + ~~~ |
| 60 | + - Tip: You can verify that your runner is using the correct credentials by inspecting the job log for `Authenticating with credentials from DOCKER_AUTH_CONFIG` |
| 61 | + - ## Troubleshooting |
| 62 | + - Permission denied pulling image |
| 63 | + - Double-check your token has read_registry scope |
| 64 | + - Ensure the CI/CD variable is of File type and your JSON is valid |
| 65 | + - Base64 line-wrap issues |
| 66 | + - Always strip newlines: `base64 | tr -d '\n'` |
| 67 | + - ## Related |
| 68 | + - [[GitLab/How To/Configure GitLab Runner]] |
| 69 | + - [[GitLab/How To/Use Private Container Registry]] |
0 commit comments