Deploy Keys

I manage a large number of Git repositories across many nested Linux user environments running in rootless namespaces and container-like setups. Access to these environments is done via (e.g.)sudo machinectl shell codimd@ under restricted user contexts, which makes standard SSH workflows such as SSH agent forwarding unreliable or not possible at all.

As a result, maintaining access to Git remotes for frequent pushes becomes quite cumbersome. So far, I relied on personal access tokens hardcoded in HTTPS git origin URLs. I had to replace these tokens regularly, because they would expire after (e.g.) a year. Conversely, propagating the SSH authentication socket through isolated sessions proved difficult.

The solution for these contexts: Gitlab Deploy Keys. Don’t confuse this with Gitlab Deploy Tokens. Unlike tokens, deploy Keys are only available in projects, not groups. You can find project deploy keys under Project → Settings → Repository → Deploy Keys.

1. Generate SSH key

ssh-keygen -t ed25519 -f ~/.ssh/gitlab-deploy -N ""

2. Show public key

cat ~/.ssh/gitlab-deploy.pub

3. Add key in GitLab

Project → Settings → Repository → Deploy Keys

• Paste public key
• Enable: “Write access allowed”
• Add key

4. Configure git to use SSH key

This directly hooks your repo to the pecific deploy key:

git config core.sshCommand "ssh -i ~/.ssh/gitlab-deploy -o IdentitiesOnly=yes"

5. Switch repo remote to SSH

git remote set-url origin git@gitlab...:<group>/<repo>.git

6. Push test

git push

Deploy Tokens

A Git Deploy Key (SSH) only works for Git operations. For the Docker Registry, HTTP-based authentication is needed.

The easiest, most secure, and standard way to do this for a server is to create a GitLab Deploy Token.

1. Create a Deploy Token in GitLab

1. Go to your GitLab project: Settings -> Repository.
2. Expand the Deploy tokens section.
3. Click Add token:
   • Name: Server-Pull-Token (or similar).
   • Username: (Leave blank, it will generate one).
   • Scopes: Check read_registry only.
4. Click Create deploy token.
5. Copy the username and password immediately (you won’t see the password again).

2. Log in on your VM and use it

Perform the docker login (use your gitlab registry!):

docker login gcr.hrz.tu-chemnitz.de

• Username: (The generated username from GitLab, e.g., gitlab+deploy-token-123)
• Password: (The generated password)

3. Pull the Image

Now that the credentials are stored in ~/.docker/config.json, your docker compose commands will work seamlessly, e.g.:

docker compose pull
docker compose up -d

Note: A one-liner:

echo "TOKEN" | docker login gcr.hrz.tu-chemnitz.de -u "USERNAME" --password-stdin