Use SSH keys to clone git repositories

This topic explains how to create an SSH key for your Git repository, store that secret in IAG’s secret store, and associate the SSH key with an IAG repository. You can then use the key during service execution when a repository is cloned.

This process is necessary if your repository uses SSH-based authentication to perform a Git clone. IAG supports SSH authentication but doesn’t support HTTP authentication for Git clones performed during service execution.

Prerequisites

You must have an IAG secret store configured with an encryption key. If you haven’t created your secret store yet, see Configure IAG secret store.

Use SSH key to access git repositories

Generate Git SSH key

Use SSH keygen to generate a key specifically for use with IAG:

$ ssh-keygen
$ Generating public/private ed25519 key pair.
$ Enter file in which to save the key (/Users/jared/.ssh/id_ed25519): ./gateway-git-key
$ Enter passphrase (empty for no passphrase):
$ Enter same passphrase again:
$ Your identification has been saved in ./gateway-git-key
$ Your public key has been saved in ./gateway-git-key.pub
$ The key fingerprint is:
$ SHA256:CqPZH763k3ktyGB5JcGH1j97CQzr2bg3h6I0Vm4j4+Q jared@Jareds-MacBook-Pro-2.local
$ The key's randomart image is:
> +--[ED25519 256]--+
> |       . o       |
> |        = +      |
> |       . o =     |
> |        . o =    |
> |    o  .S+.+ + . |
> |   + o+..o+ o o  |
> |  o ..o+B++o o   |
> |     o BB==.= .  |
> |      +oE= + o   |
> +----[SHA256]-----+

The output shows that the system generated the private and public SSH key in your current directory:

ls | grep git-key
gateway-git-key
gateway-git-key.pub

You need to place the file content from gateway-git-key.pub in your preferred Git service as a new authentication key.

For this demonstration, we use GitLab. Navigate to the GitLab SSH Settings to see all your keys listed. Click Add new key and paste in the contents of your SSH public key.

Add private key to IAG secret store

After your public key is in GitLab, add your private key to IAG’s secret store. Run the following command where the private key is located:

$ iagctl create secret git-key --value "@/path/to/new/ssh/key/for/gateway/gateway-git-key"
$ Successfully created secret
$ Name:   git-key

The command uses the ”@” symbol to indicate that this is a file with the full path to the private key. In this case, the private key is the gateway-git-key file created by your SSH keygen command.

You can view the contents of the SSH key in IAG’s secret store:

$ iagctl describe secret git-key

To securely output the decrypted data, the system saves the secret in a temporary location and displays it in your default editor. If you don’t set an editor, IAG defaults to vim. The editor is determined by your $EDITOR environment variable. To set a different $EDITOR:

$ export EDITOR=nano

When you close your editor, the system deletes the file that displayed your secret’s contents.

Reference SSH key on repository creation

When you create a repository, you can pass in the SSH key’s name in the secret store using the --private-key-name flag:

$ iagctl create repository some-private-repo --url git@gitlab.com:example/automations/example-automations.git --private-key-name git-key
$ Successfully created the repository
$ Name:             some-private-repo
$ Description:
$ Url:              git@gitlab.com:example/automations/example-automations.git
$ Reference:
$ Tags:
$ Private Key Name: git-key

When you create a service, reference the repository resource that you just created. IAG will authenticate with your Git server.