Adding SCM Credentials To ManageIQ

Credentials are a critical component to application integrations. Debugging credential errors can be maddening. In this post I’m sharing my learnings on how to add Source Control Management (SCM) credentials to ManageIQ (to be used, in this case, for importing Ansible Playbooks for use in Embedded Ansible). Special thanks to @fryguy, @NickLaMuro and @pemcg for their support in figuring this all out.

My instructions are GitLab specific, but GitHub should be very similar:

It is advised that we use ssh (not https) for maximum security.

Steps to generate credentials and pull in a repo from GitLab:

1. Generate a pair of ssh keys (on your local machine or on a server). There are many guides online for how to do this using ssh-keygen. Unless you opt to name them something else, it’ll create a public key file called id_rsa.pub and a private key file called id_rsa. In your command line you can use cat file_name to view, select, and copy the contents. (You’ll need this to paste the keys in GitLab and ManageIQ.) Put the public key in gitLab. (Got to your profile->Settings-> SSH keys.) Note that: a. The name of the key you save is not part of the authentication process so you can name it whatever you want. b. Extra spaces or carriage returns in the key (happens at the beginning/end of the text usually) can mess it up. c. The SHA256 fingerprint is displayed after you save it. You can always come back and view it later if you need to debug your keys, but for now just note that it’s available in GitLab when you open a key.
2. Create a new credential object in ManageIQ: a. In MIQ, go to Automate–>Ansible–>Credentials, under Configuration choose ‘Add A New Credential’ b. Name the credential c. For Type choose Scm (Source Control Management, i.e., Git) d. For username choose “git”. e. Leave password blank f. If you used a passphrase when generating your ssh keys provide that in “Private Key Passphrase”. Otherwise leave it blank. g. Paste your private key in the field named Private Key. This would be the file contents of the id_rsa file generated when you created your keys. h. Click Add
3. Now you can add a repository in ManageIQ. a. Click on Automation --> Ansible–> Repositories. Under Configuration choose Add new Repository. b. Name it c. Under URL provide the SSH url from your project in GitLab. Note that it should begin with [e-mail]…. and end with .git. d. Under SCM Credentials select the credential object you just created in step 3. e. Optionally choose the branch. I recommend you choose master. f. Click Add
4. Now you can see your playbooks (if there are any in your GitLab project) under Automation–>Ansible–>Playbooks

How To Debug your Credentials if It Fails to Sync the Repository from GitLab
Basically you need to confirm that the public key you put in the credential object in ManageIQ has a corresponding public key in GitLab. The other thing that can go wrong is the passphrase used to create the keys in the first place. If you forgot your passphrase or don’t remember if you used one, you’ll need to start over and get that part right. But assuming that’s not the problem, you need to figure out whether it’s your private key in ManageIQ or public key in GitLab that’s missing/messed up.

1. Check your key fingerprints on your machine where you created the keys: a. Both the private and public key have the same fingerprint. It can be in one of several formats (SHA256 or MD5). I’ll use SHA256 in these exampls. b. On your local machine, cd into the dir where your id_rsa and id_rsa.pub keys are. c. Run ssh-keygen -lf id_rsa to print the SHA256 fingerprint of the private key. d. Optionally run ssh-keygen -lf id_rsa.pub to print the SHA256 fingerprint of the public key. These two will match.
2. View your SSH key fingerprints in GitLab a. Go to profile–>settings–>ssh keys and inspect each key to see if any has a SHA256 fingerprint matching what you found on your machine where you created the keys. If not, then you haven’t properly saved your id_rsa.pub key to GitLab. b. Note that extra spaces or carriage returns in the key can mess it up, as mentioned previously. c. If you find a matching fingerprint, proceed to check the keys in ManageIQ.
3. View your known hosts on the ManageIQ server a. Whenever you add a private key, it adds the finger print of the key as a known host to a key file found at ~/.ssh/known_hosts b. Run ssh-keygen -l -f known_hosts and it will print a list of fingerprints on the list. c. Check whether the fingerprint from step 2 and 3 is also found in this list. If not, then there was a problem with how you set up your credential object with the private key. Delete the object in ManageIQ and do it over following the steps above. d. If the fingerprint does not appear in the list, you can also inspect your credential object to pull the fingerprint from it directly: i. From /var/www/miq/vmdb enter the rails console by typing rails console. ii. Once in, run this command (updating the name of the credential to whatever you named it:) GitRepository.find_by(:name => "name_of_credential").authentication.auth_key This should print the contents of your private key. To extract the fingerprint, we need to do a few more steps: iii. Also in the rails console, run: File.write("/tmp/fookey", GitRepository.find_by(:name => "name_of_credential").authentication.auth_key) This will generate a key-like file called fookey in your tmp folder. iv. Run chmod 600 /tmp/fookey so that so that, (U)ser / owner can read, can write and can’t execute. v. Get out of the ruby console, and cd /tmp vi. Run ssh-keygen -y -f fookey3 > fookey.pub to create a public key from the private key. vii. Run ssh-keygen -lf fookey(same as from step 2 above) to print the fingerprint. If this doesn’t match your fingerprint in GitLab, you won’t be able to authenticate.

How To create an HTTPS connection with GitLab
As mentioned above, it is recommend to use an SSH connection, but it is possible and valid to use https.

1. Create a new credential object in ManageIQ: a. In MIQ, go to Automate–>Ansible–>Credentials, under Configuration choose ‘Add A New Credential’ b. Name the credential c. For Type choose Scm (Source Control Management, i.e., Git) d. For username and password, provide a username and password that have access to your repository in GitLab. e. Leave the following fields blank: “Private Key Passphrase”, “Private Key” f. Click Add
2. Now you can add a repository in ManageIQ. a. Click on Automation --> Ansible–> Repositories. Under Configuration choose Add new Repository. b. Name it c. Under URL provide the https url from your project in GitLab. Note that it should begin with https://…. and end with .git. d. Under SCM Credentials select the credential object you just created in step 1. e. Optionally choose the branch. I recommend you choose master. f. Click Add
3. Now you can see your playbooks (if there are any in your GitLab project) under Automation–>Ansible–>Playbooks

I suspect the same process would apply more or less for adding credential objects to AWX/Ansible Tower. Others can comment on whether or not that is the case.