Skip to main content
While Omni generates SSH deploy keys automatically when you connect a Git repository, you can also supply your own RSA or ED25519 private key via the API. If you need to rotate keys—for example, to meet a compliance schedule—the API approach allows you to avoid downtime during the rotation. You first authorize the new public key with your Git provider, supply the private key to Omni, and then remove the unneeded public key from Git. This ensures that both keys work during the transition. The new key will take effect on the next Git operation.

Requirements

To follow the steps in this guide, you’ll need:
  • An Omni API key
  • Connection Admin permissions on the model
  • A Git-connected model using SSH authentication
  • The shared model’s modelId, which you can retrieve using the List models endpoint
  • ssh-keygen installed locally to generate keypairs

Supported key types

Omni accepts RSA and ED25519 private keys in PEM format:
  • OpenSSH format (default from ssh-keygen)
  • PKCS#1 format
  • PKCS#8 format
Keys can be passphrase-protected or unencrypted. When you supply an encrypted key, Omni uses the passphrase once to decrypt it, then stores the key under its own encryption at rest. The passphrase is not retained.
1

Generate a new keypair

Use ssh-keygen to generate a new RSA or ED25519 keypair.
When prompted for a passphrase:
  • To leave the key unencrypted, press Enter.
  • To encrypt the key, provide a passphrase. This is more secure at rest, but you’ll need to supply it to Omni.
This generates two files:
  • omni_deploy_key — The private key, which you’ll supply to Omni
  • omni_deploy_key.pub — The public key, which you’ll authorize with your Git provider
2

Authorize the public key with your Git provider

Add the public key (omni_deploy_key.pub) to your Git repository as a deploy key with write access. This step ensures the new key is authorized before you supply the private key to Omni.
  1. In the GitHub repository, click the Settings tab.
  2. Click Deploy keys, located in the Security section of the left navigation.
  3. Click Add deploy key.
  4. Fill in the fields as follows:
    • Title - Enter a descriptive title to help you identify what the key is used for. For example, Omni Snowflake Model
    • Key -
    • Allow write access - Check this box, which will allow Omni to push changes made in Omni to the repository
  5. Click Add key.
3

Supply the private key to Omni with the API

Next, call the Update Git configuration API and provide the private key.
In the terminal, navigate to the same location where the omni_deploy_key file was saved. Then, run the following:
Replace the following variables:
  • <your-subdomain> - Your Omni subdomain
  • <MODEL_ID> - The shared model’s UUID
  • <YOUR_API_TOKEN> - Your Omni API key
A successful response will include the derived public key in the publicKey field.
If you run into issues, see the Troubleshooting section.
4

Verify the new key works

To verify the setup, navigate back to the Git settings page in Omni. Click the Test git connection button near the top of the page to test the connection.Alternatively, call the Sync model with Git repository endpoint:
If the connection test or sync succeeds, the new key is working correctly.
5

Remove the old key from your Git provider

Once you’ve confirmed the new key works, remove the old deploy key from your Git provider’s settings.

Troubleshooting

The private key must be in PEM format (OpenSSH, PKCS#1, or PKCS#8) and be a valid RSA or ED25519 key. Common causes:
  • The key file is corrupted or incomplete
  • The key is in an unsupported format (for example, PuTTY .ppk format)
  • The key file contains extra whitespace or characters
Regenerate the key with ssh-keygen and try again.
The passphrase you provided does not match the passphrase used to encrypt the private key. Verify the passphrase and retry.If you’ve forgotten the passphrase, you’ll need to generate a new keypair and start the rotation process again.
The private key is passphrase-protected, but you didn’t supply deployKeyPassphrase in the request. Either:
  • Provide the passphrase via the deployKeyPassphrase field
  • Or generate a new unencrypted key (press Enter when ssh-keygen prompts for a passphrase)
You included deployKeyPassphrase in the request body without deployPrivateKey. Remove deployKeyPassphrase or include deployPrivateKey.
Custom deploy keys are only supported for SSH authentication. If your model uses HTTPS token authentication (authMethod: https_token), you cannot supply a custom deploy key. HTTPS token connections rotate via the token field instead.To use custom deploy keys, switch your model to SSH authentication.
If Git operations fail after rotating the key:
  1. Verify the public key was added to your Git provider with write access.
  2. Verify the public key in the API response matches the public key you added to your Git provider (compare the publicKey field in the response to the contents of omni_deploy_key.pub).
  3. Check your Git provider’s webhook logs for authentication errors.
If the issue persists, re-add the public key to your Git provider and retry the rotation.

Next steps