How to Integrate Jenkins & Multiple Github Repo using SSH Keys

How to Setup Multiple GitHub Repo SSH Auth with Jenkins CI/CD pipeline

If you have been working on setting CI/CD pipelines and integration between CI tools such as Jenkins and your Github source code management. You’ll notice that GitHub doesn’t let you use a username and password within a CI/CD pipeline. Using username and token doesn’t quite work as expected in some cases as well and returns an error similar to this:

Failed to connect to repository : 
Command "C:\Git\bin\git.exe ls-remote -h -- https://github.com/orgName/repoName HEAD" 
returned status code 128:
stdout:
stderr: remote: Repository not found.
fatal: repository 'https://github.com/orgName/repoName/' not found

In this article, I will discuss how to set up SSH authentication and integrate multiple GitHub repositories with the Jenkins CI/CD tool ( my Jenkins instance is running on-prem). Using SSH authentication is actually the best security practice for your IT resources. I’d highly recommend that you check out CI/CD security to learn more about how to keep your CI/CD pipeline secure.

Important Note:

• In this example, my Jenkins Master and Agents nodes are installed and running on a windows server 2019
• Make sure that Port 22 is open on the Jenkins master node on the Windows server
• Make sure that Git is installed on the Jenkins master and all its agent nodes
• Make sure a plugin called Credentials Plugin is installed on Jenkins
• If it’s not already installed → Go to Manage Jenkins → Manage Plugins → Available and search for credentials plugin and install it

How does SSH work?

How SSH auth works — Diagram — For more details check out (source): foxpass.com

Generate SSH keys

So we’re going to get started with generating the SSH keys. For best security and organization practice, I’d recommend using “your Jenkins service account” for this setup.

Make sure that you log in to your Jenkins master server with your jenkins service account → which will be the username used when you add the SSH auth creds to Jenkins.

Very Important Note: —The SSH keys are generated on the Jenkins master node — Not the agent node

• Open Gitbash → type: whoami (this is the account that’ll create the SSH Keys)
• The default .ssh directory will be C:\Users\yourJenkins.srv\.ssh → This is also where the new SSH keys you generate will be stored.
• Generate an ssh key pair with → ssh-keygen -t rsa
• Give the custom location and name of the file in a way that makes sense to you. I recommend the following naming standard: C:\Users\yourJenkins.srv\.ssh\id_rsa_NameOfRepository
• Leave the password Empty → press “enter”
• This will generate your private (id_rsa_NameOfRepository) and public key (id_rsa_NameOfRepository.pub)
• Open id_rsa_NameOfRepository.pub file on a notepad → Copy all its content. This is the SSH public key you’ll add to your GitHub repo deploy setting.

# do this on the Jenkins master
# DRP with yourJenkins.srv account on the Jenkins server
whoami
 
# Open Gitbash
# cmd to generate an ssh key pair and give the above location to save keys:
ssh-keygen -t rsa

# provide the custom name with the full path:
/c/Users/yourJenkins.srv/.ssh/id_rsa_NameOfRepository

# Leave the password Empty → press "enter"
# *--------------------------------------------------------------------*

# after succefully creating the new SSH keys 
# get the SSH public key
cd  C:\Users\yourJenkins.srv\.ssh
cat id_rsa_NameOfProject.pub
 
# Since your new SSH key does not have the default filename (/.ssh/id_rsa), 
# you'll have to pass that path to ssh-add.
# start the ssh-agent in the background
$ eval "$(ssh-agent -s)"
> Agent pid #####
 
# pass the new key ( this is an example, change he naming accordingly)
$ ssh-add /c/Users/yourJenkins.srv/.ssh/id_rsa_NameOfRepository
 
# the successful output should look something like this:
Identity added: /c/Users/yourJenkins.srv/.ssh/id_rsa_NameOfRepository 
(yourJenkins.srv@YOURJENKINSERVER)
 
# test that your jenkins service account can successfully connect to 
# the GitHub repo
 ssh -T git@github.com
 
# the successful output should look something like this:
Hi OrgName/NameOfRepo! You have successfully authenticated, 
but GitHub does not provide shell access.
 
# to further test, try cloning the repo:
git clone git@github.com:OrgName/NameOfRepo.git

Add SSH Public Key to GitHub Repo

• Login to GitHub → go to the project repository
• Go to repository settings → Deploy keys → Add deploy key
• Or Click on Settings and then navigate to Deploy Keys.
• Click on “Add Deploy Key” on the right side of your screen.
• Give your deploy key a “Title”. Make sure your “Title” is representative of its purpose like → Jenkins CI/CD SSH auth
• Copy and Paste the Public key you generated
• ~Optional~ If you need the build system to Write to your repository, then make sure you check the “Allow write access” box. If the build system is only Reading from your repository, do not check that box.

In most cases will NOT need to check the “Allow write access” box.

• Finally, Click Add Key

Configure SSH Auth Credential on Jenkins

Go to the project Jenkins’ Job → Configure → Go to Source Code Management section → Select Git → under the credentials, select +Add

This will open the Jenkins Credentials Provider: add Credentials:

• Scope/Domain dropdown, select Global (Default selection)
• Kind dropdown, select ‘SSH username with private key’.
• ID → leave this empty
• Description → add some description with the following: SSH auth for Github repo_Name
• Username → this is the Jenkins service account name: yourJenkins.srv
• For private key → Select “Enter private key directly, past the SSH private key you generated: id_rsa_NameOfRepository
• passphrase → leave this empty

After that, click ok to save the credentials.

Image source: twilio.com

Integrate GitHub Repo to your CI/CD Jenkins pipeline Job

• Go to your project Jenkins Job
• Under Configure → Source Code Management
• Add the GitHub repo SSH Clone URL
• select the appropriate SSH auth credentials you configured
• make sure there are no error and everything look good — Build the job and review

Repeat the same process for all the other repo you want to integrate with your Jenkins CI/CD build and deploy pipeline.

If you have a Multi-Factor or 2-Factor Authentication (MFA or 2FA) configured on your GitHub organization account, rest easy since SSH Git authentication will bypass all the MFA or 2FA authentication.

This process and steps might be similar but not the same if you’re running your Jenkins instance on a Linux Server. So if that is the case for you, give it a try and leave a comment on how you went about it!

if you like this, you might also like: “How to Setup SSH for Source Code Management to Local Machine”

Cheers!!!