Provide instructions on how to use a specific SSH key (#9500)

* Adding instructions to use a specific SSH key

* Making paragraph easier to read

* Rewording

* Rewriting note

* Rewriting (more specific)

* Implementing review suggestions

* Implementing suggestions to improve clarity

---------

Co-authored-by: Rosie Yohannan <[email protected]>

Author: yaningo

docs/guides/modules/integration/pages/add-ssh-key.adoc

@@ -18,7 +18,7 @@ See the following VCS-specific docs for additional details on creating SSH keys:
 ****
 
 [#steps-to-add-additional-ssh-keys]
-== 1. Add an additional SSH key to your project
+== Add an additional SSH key to your project
 
 CircleCI cannot decrypt SSH keys, therefore every new key must have an empty passphrase. The below examples are for macOS.
 
@@ -35,7 +35,7 @@ If you have a GitLab integration, you will find that an additional SSH key alrea
 . Select *Add SSH Key*.
 
 [#add-ssh-keys-to-a-job]
-== 2. Add SSH keys to a job
+== Add SSH keys to a job
 
 Even though all CircleCI jobs use `ssh-agent` to automatically sign all added SSH keys, you *must* use the `add_ssh_keys` key to actually add keys to a container.
 
@@ -63,9 +63,49 @@ All fingerprints in the `fingerprints` list must correspond to keys that have be
 To checkout additional repositories from within your job, ensure that you run the `checkout` command *before* `add_ssh_keys`; otherwise, `CIRCLE_CI_REPOSITORY_URL` will be empty.  Also ensure that the private key is added to the CircleCI project and that the public key has been added to the additional repositories that you want to checkout from within your job.
 
 [#adding-multiple-keys-with-blank-hostnames]
-== Adding multiple keys with blank hostnames
+=== Adding multiple keys with blank hostnames
 
-If you need to add multiple SSH keys with blank hostnames to your project, you will need to make some changes to the default SSH configuration provided by CircleCI. In the scenario where you have multiple SSH keys that have access to the same hosts, but are for different purposes the default `IdentitiesOnly no` is set causing connections to use `ssh-agent`. This will always cause the first key to be used, even if that is the incorrect key. If you have added the SSH key to a container, you will need to either set `IdentitiesOnly no` in the appropriate block, or you can remove all keys from the `ssh-agent` for this job using `ssh-add -D`, and reading the key added with `ssh-add /path/to/key`.
+If you add multiple SSH keys with blank hostnames to your project, you will need to make some changes to the default SSH configuration provided by CircleCI.
+
+If you have multiple SSH keys for different purposes that have access to the same hosts, the default `IdentitiesOnly no` is set, which causes connections to use `ssh-agent`.
+
+In this scenario the first key is used regardless of whether it is the correct key. If you have added the SSH key to a container, you will need to either set `IdentitiesOnly yes` in the appropriate block, or you can remove all keys from the `ssh-agent` for the job using `ssh-add -D` and read the added key using `ssh-add /path/to/key`.
+
+[#using-specific-ssh-keys-for-a-job]
+=== Using specific SSH keys for a job
+
+[NOTE]
+====
+SSH keys are named using MD5 fingerprints with colons removed from the hash.
+
+To retrieve the MD5 fingerprint of an SSH key, run this command locally:
+
+`ssh-keygen -l -E md5 -f ~/.ssh/your_key_name`
+
+The filename follows this format:
+
+`id_rsa_[MD5_fingerprint_without_colons]`
+
+Example:
+
+- SSH key MD5 fingerprint: `a3:f9:82:c5:1d:47:9b:e6:88:32:a1:bc:f4:29:7e:15`.
+
+- SSH key filename: `id_rsa_a3f982c51d479be68832a1bcf4297e15`.
+====
+
+
+If you have added multiple SSH keys for the same hostname to your project and want to use a specific key in your SSH commands, follow these steps:
+
+. Add the SSH key to the job using the `add_ssh_keys` step.
+. Use the `-i` parameter to specify the exact SSH key file path in your SSH commands.
+. Add the `-o "IdentitiesOnly=yes"` option to prevent SSH from using other keys from the SSH agent.
+
+Example:
+
+[source,bash]
+----
+ssh -i ~/.ssh/id_rsa_a3f982c51d479be68832a1bcf4297e15 -o "IdentitiesOnly=yes" user@hostname
+----
 
 [#see-also]
 == See also