GitHub Deploy Keys¶
A deploy key gives ComposeFlux read-only SSH access to the stacks repository. The same approach works with other Git providers.
Generate a key pair¶
This creates the private key ~/.ssh/composeflux_deploy and the public key ~/.ssh/composeflux_deploy.pub. Do not
set a passphrase; ComposeFlux runs unattended.
Add the public key to GitHub¶
-
Copy the public key:
-
Open the repository on GitHub.
- Go to Settings, then Deploy keys, and click Add deploy key.
- Paste the key and leave write access disabled.

Provide the private key to ComposeFlux¶
Use one of the following options.
Mount the key¶
Mount the private key at GIT_SSH_KEY_PATH. The default path is /.ssh/composeflux_id_rsa.
services:
composeflux:
image: ghcr.io/veerendra2/composeflux:latest
environment:
GIT_REPO_URL: git@github.com:user/repo.git
STACK_PATH: stacks
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ~/.ssh/composeflux_deploy:/.ssh/composeflux_id_rsa:ro
- compose-stack:/opt/compose-stack
volumes:
compose-stack:
Store the key in a secrets manager¶
This option requires Bitwarden or Infisical credentials. Set GIT_DEPLOY_KEY_SECRET_REF to the secret reference:
- Bitwarden: the secret ID.
- Infisical: the secret key name, for example
SSH_PRIVATE_KEY.
At startup, ComposeFlux fetches the value and writes it to GIT_SSH_KEY_PATH with mode 0600. When the reference is
empty, ComposeFlux uses the key already present at that path.
Do not also mount the key at GIT_SSH_KEY_PATH: a read-only mount makes the write fail at startup.
environment:
GIT_REPO_URL: git@github.com:user/repo.git
STACK_PATH: stacks
GIT_DEPLOY_KEY_SECRET_REF: SSH_PRIVATE_KEY
INFISICAL_CLIENT_ID: ${INFISICAL_CLIENT_ID}
INFISICAL_CLIENT_SECRET: ${INFISICAL_CLIENT_SECRET}
INFISICAL_ENVIRONMENT: prod
INFISICAL_PROJECT_ID: ${INFISICAL_PROJECT_ID}
See Bitwarden or Infisical for adding the secret.
Trust a self-hosted Git host¶
The image trusts github.com and gitlab.com because their host keys are added to
/etc/ssh/ssh_known_hosts at build time. Any other SSH host, such as a self-hosted Gitea, Forgejo, or GitLab, or a server
on a non-default port, must be added. Without an entry, the clone fails with knownhosts: key is unknown.
Generate the file on the Docker host, because the distroless image does not include ssh-keyscan:
Do not use -t to limit the key type. An entry with only one host key type can fail with knownhosts: key mismatch,
because go-git negotiates a different type. For a non-default SSH port, scan with -p 2222 and clone with
ssh://git@git.example.com:2222/group/repo.git.
Give the file to the container in one of two ways.
Mount over the default path¶
This replaces the built-in file, so add github.com and gitlab.com entries too if those repositories are used.
Point SSH_KNOWN_HOSTS at the file¶
environment:
SSH_KNOWN_HOSTS: /config/known_hosts
volumes:
- ~/.ssh/composeflux_known_hosts:/config/known_hosts:ro
When SSH_KNOWN_HOSTS is set, go-git uses only that file and ignores /etc/ssh/ssh_known_hosts. The file must
therefore contain every host you connect to, including the well-known providers.
Verify the host fingerprint out of band before trusting a scanned key.
Test access¶
A successful test prints a message that the key authenticated but does not provide shell access.