Skip to content

Update SSH documentation for config server #3335

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ryanjbaxter merged 1 commit into from
Oct 7, 2026
+1 −22
Merged

Update SSH documentation for config server #3335

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 1 addition & 22 deletions docs/modules/ROOT/pages/server/environment-repository/git-backend.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,35 +207,14 @@ spring:
----

If you do not use HTTPS and user credentials, SSH should also work out of the box when you store keys in the default directories (`~/.ssh`) and the URI points to an SSH location, such as `git@github.com:configuration/cloud-configuration`.
It is important that an entry for the Git server be present in the `~/.ssh/known_hosts` file and that it is in `ssh-rsa` format.
Other formats (such as `ecdsa-sha2-nistp256`) are not supported.
It is important that an entry for the Git server be present in the `~/.ssh/known_hosts` file.
To avoid surprises, you should ensure that only one entry is present in the `known_hosts` file for the Git server and that it matches the URL you provided to the config server.
If you use a hostname in the URL, you want to have exactly that (not the IP) in the `known_hosts` file.
The repository is accessed by using JGit, so any documentation you find on that should be applicable.
HTTPS proxy settings can be set in `~/.git/config` or (in the same way as for any other JVM process) with
system properties (`-Dhttps.proxyHost` and `-Dhttps.proxyPort`).

TIP: If you do not know where your `~/.git` directory is, use `git config --global` to manipulate the settings (for example, `git config --global http.sslVerify false`).

JGit requires RSA keys in PEM format. Below is an example ssh-keygen (from openssh) command that will generate a key in the correct format:

[source,bash]
----
ssh-keygen -m PEM -t rsa -b 4096 -f ~/config_server_deploy_key.rsa
----

[WARNING]
=====
When working with SSH keys, the expected ssh private-key must begin with `-----BEGIN RSA PRIVATE KEY-----`. If the key starts with `-----BEGIN OPENSSH PRIVATE KEY-----` then the RSA key will not load when spring-cloud-config server is started. The error looks like:

[source,bash]
----
- Error in object 'spring.cloud.config.server.git': codes [PrivateKeyIsValid.spring.cloud.config.server.git,PrivateKeyIsValid]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [spring.cloud.config.server.git.,]; arguments []; default message []]; default message [Property 'spring.cloud.config.server.git.privateKey' is not a valid private key]
----
=====

To correct the above error the RSA key must be converted to PEM format. An example using openssh is provided above for generating a new key in the appropriate format.

[[authentication-with-aws-codecommit]]
== Authentication with AWS CodeCommit

Expand Down
Loading