> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/clone-git-repositories-ssh/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Use SSH keys to clone git repositories

This topic explains how to create an SSH key for your Git repository, store that secret in Itential Gateway's secret store, and associate the SSH key with a Gateway 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. Gateway supports SSH authentication but doesn't support HTTP authentication for Git clones performed during service execution.

## Prerequisites

You must have a Gateway secret store configured with an encryption key. If you haven't created your secret store yet, see [Configure Gateway secret store](./configure-secret-store). Alternatively, you can use an [external secret alias](./secrets/external-secrets/manage-secret-aliases) for the `--private-key-name` value instead of a local secret.

## Use SSH key to access git repositories

#### Generate Git SSH key

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

```bash
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 Gateway secret store

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

```bash
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 Gateway's secret store:

```bash
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, Gateway defaults to vim. The editor is determined by your `$EDITOR` environment variable. To set a different `$EDITOR`:

```bash
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:

```bash
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. Gateway will authenticate with your Git server.