Docker secrets - Using your SSH key during the build process

There are plenty of articles on the Internet but I didn't find the one that allowed me, without an impressive amount of trial and error, to find the solution.

So here's another article to add to the long list: how to access a private project stored on Github when creating a Docker image. In other words, the SSH key is not stored in the image. Docker will just use your key when executing the project recovery layer (the one containing the git clone instruction) and will not keep track of the key afterwards.

My use case: I wish to build a Docker image and during the build phase, I need to grab a copy of a private repository I've put on github.com. The CI equivalent of this problem — pulling a private Docker image rather than a private repository — is covered in GitLab - Using Docker private images.

When I access the container, the project will then be available but I don't have, anywhere in my image, a copy of my SSH key so I won't be able to run a git pull f.i. since no further authentication is possible.

Preview​

That's the proof the technique works: the SSH key was used to authenticate against GitHub during the build — without ever being baked into the final image.

Why it works​

• Docker's RUN --mount=type=secret mounts the secret only for the duration of that one build layer — it never gets written to a layer that ends up in the final image.
• Copying your SSH key into the image instead (or hardcoding a token) is a serious design error: anyone reading the Dockerfile, or starting an interactive bash session and running printenv or browsing .ssh/.git folders, will find it.
• Even a secret deleted in a later layer can survive: tools like SecretScanner do deep layer-by-layer scanning and will still find it if it was ever written to disk in an earlier layer. The same reasoning applies to your git history: Git - pre-commit-hooks lists hooks that block a commit as soon as a credential is detected.

Which key to use​

It's important to know which key has been used to link your Github profile.

You can just display the file to your console like f.i. cat ~/.ssh/id_ed25519.pub or cat ~/.ssh/id_rsa.pub (the public key file) and look at the end: is the mentioned email is the one you're using on Github.com? If yes, you've probably identified the key.

In my case, the key I've used for github.com is id_ed25519 so I'll use that one in the next chapter.

Creating files​

We'll need two files: compose.yaml and Dockerfile.

compose.yaml​

Here is my compose.yaml content:

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      // highlight-next-line
      secrets:?
        // highlight-next-line
        - my_ssh_key?
      args:
        // highlight-next-line
        - KEY_NAME=id_ed25519?

// highlight-next-line
secrets:?
  // highlight-next-line
  my_ssh_key:
    // highlight-next-line
    file: ${HOME}/.ssh/id_ed25519?

As you can see, we've five specific lines.

In our services -> app --> build entry, we should add the secrets and the name of one (or more) secrets.

I've also added an argument called KEY_NAME just because I need to inform Docker which key I'm using (is it id_ed25519 or id_rsa or another one).

Secrets have to be defined at the same indentation level of services and the notation is this one:

secrets:
  a_secret_name:
    file: existing_file?

You can use what you want for a_secret_name; for instance, my_ssh_key.

Dockerfile​

Time to create our second file, Dockerfile:

FROM alpine:3.19

ARG KEY_NAME="id_rsa"?

USER root

RUN apk add --no-cache bash ca-certificates git openssh-client?

// highlight-next-line
RUN mkdir -p -m 0700 /root/.ssh && ssh-keyscan "github.com" >> /root/.ssh/known_hosts?

// highlight-next-line
RUN --mount=type=secret,id=my_ssh_key,dst=/root/.ssh/${KEY_NAME} \?
    // highlight-next-line
    mkdir -p /app && cd /app \
    // highlight-next-line
    && ssh -T git@github.com || true \?
    // highlight-next-line
    && git clone git@github.com:cavo789/my_private_repo.git

WORKDIR /app

# Keep the container running
ENTRYPOINT ["tail", "-f", "/dev/null"]?

As you can see, we are setting KEY_NAME="id_rsa" as the default value (but will be overwritten by our declaration in the yaml file) then later on, we need to create the /root/.ssh folder and we are adding github.com in the list of known hosts.

The most important thing comes then. We should use the RUN --mount=type=secret syntax to inform Docker that this layer will use a Docker secret. We need to provide the name of our secret (which was set in our yaml file and it's my_ssh_key here) then we need to define where that secret has to be stored during this layer. Our variable KEY_NAME finds its use here: our SSH key was id_ed25519 and this is the value of the KEY_NAME variable.

So, in short --mount=type=secret,id=my_ssh_key,dst=/root/.ssh/${KEY_NAME} will be translated to --mount=type=secret,id=my_ssh_key,dst=/root/.ssh/id_ed25519.

During this layer thus, our local SSH key will be saved to /root/.ssh/id_ed25519. The other lines in that RUN layer will first create a /app folder, jump in it, then run ssh -T git@github.com just for debugging (we expect to see on the screen Hi your_name! You've successfully authenticated) and finally we're git cloning our private repository using SSH.

Create the image and jump in the container​

Ok, so you've the created the two files on your hard disk.

Run docker compose --progress plain build --no-cache in your console to build the image and enable the verbose mode.

As you can see, we can confirm that our SSH key was shared during the build process — that's the "You're authenticated" output shown at the top of this article.

You'll now create the container; by running docker compose up --detach.

Now, just to check, we can jump inside the container by running docker compose exec app /bin/bash.

We can verify that our key wasn't stored in the image by running ls -alh /root/.ssh/

We can check too: jumping in our project folder and running git pull will fail with the error below:

git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
▋

And this is what we expect: our key isn't part of the image so we can't connect anymore to Github.

Sharing your keys also with the container​

Ok, we've seen how to share the SSH key with Docker but only during the build phase. As we've seen above, jumping in the container and running git pull has failed; exactly what we wanted in the previous chapter.

But now, if we need to share our key also with the container so we can work on the project, update it and push changes / pull modifications, how to do?

Please edit the compose.yaml file and add these two lines:

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      secrets:?
        - my_ssh_key
      args:
        - KEY_NAME=id_ed25519?
    // highlight-next-line
    volumes:
      // highlight-next-line
      - ${HOME}/.ssh:/root/.ssh?

secrets:
  my_ssh_key:?
    file: ${HOME}/.ssh/id_ed25519

Then recreate the container by running docker compose up --detach. Jump in the container by running docker compose exec app /bin/bash and go in your project folder. Now, by running git pull, as you'll see, it'll work.

Why? Because your SSH keys are now part of the container as we can see by running ls -alh /root/.ssh:

services:
  app:
    [...]
    // highlight-next-line
    volumes:?
      // highlight-next-line
      - ${HOME}/.ssh:/root/.ssh?

services:
  app:
    [...]
    // highlight-next-line
    volumes:
      // highlight-next-line
      - ${HOME}/.ssh:/christophe/.ssh?

Conclusion​

Two different needs, two different mechanisms: a build-time secret (--mount=type=secret) that never touches the final image, for one-off operations like cloning a private repo during docker build; and a bind-mounted volume, for when the running container itself needs your key on an ongoing basis to git pull/push. Pick the first by default, and only add the second when you actually need to work from inside the container.