How to configure SSH git settings using the API

Pre-Requisites

You will need to attain a copy of a private SSH key configured to your source control. If you do not have an SSH key configured to access your source control account, you will need to generate a new SSH key and configure your git repository. We highly recommend using machine users to authenticate and authorize git syncing.


Github: https://docs.github.com/en/developers/overview/managing-deploy-keys#machine-users 

Bitbucket: https://confluence.atlassian.com/bitbucketserver/ssh-access-keys-for-system-use-776639781.html

Once you have attained your private SSH key, you will need to convert it to the following sample format:

-----BEGIN OPENSSH PRIVATE KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCH63TY3t3pOuuGhgGFir7Y8IxeEz2ZuxUgL6ha4bPRKIcVH6Mk1stdPKhMUXJ/l1pqGVnLQRL0QaF0Lhu6+Qlc78ZFkHuYUuJS2Qw5eN1sKnVh72XHY+UrygB9GRYaohvc/ksZeBXp+inRr3WqNgKMNQW6/3kojDi5xNJiulutBwIDAQAB\n-----END OPENSSH PRIVATE KEY-----

This format requires you to pass the full key in a single line while making sure to include \n prepending and appending the key. We recommend using our helper bash script to format your private key: https://gist.github.com/BoVice/f882e9c2b7a037a963fcf6aceb5e1965


Create SSH credentials via API

Once you have your private SSH key created on your repo, you will need to create the two secret objects required for configuring SSH authentication: passphrase and key.

The following are example API endpoints and payloads for configuring SSH for system creation and system updates:

Create a secret passphrase id

Endpoint: PUT /v1/secrets/git/ssh/passphrase

A passphrase secret is required for system configuration. You may leave the secret empty if using a passphrase-less key.

Example parameters:

{
"description": "passphrase for git ssh key",
"name": "prod1-passphrase",
"secret": ""
}

Create a secret SSH private key

Endpoint: PUT /v1/secrets/git/ssh/key

Example parameters:

{
"description": "git ssh key",
"name": "prod1-ssh-key",
"secret":"-----BEGIN OPENSSH PRIVATE KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCH63TY3t3pOuuGhgGFir7Y8IxeEz2ZuxUgL6ha4bPRKIcVH6Mk1stdPKhMUXJ/l1pqGVnLQRL0QaF0Lhu6+Qlc78ZFkHuYUuJS2Qw5eN1sKnVh72XHY+UrygB9GRYaohvc/ksZeBXp+inRr3WqNgKMNQW6/3kojDi5xNJiulutBwIDAQAB\n-----END OPENSSH PRIVATE KEY-----"
}

Create a new system

Endpoint: POST /v1/systems

Doc: https://square.styra.com/v1/docs/redoc.html#operation/CreateSystem

Example parameters:

{
"name": "production-system-1",
"type": "kubernetes",
"deployment_parameters": {
"kubernetes_version": "1.17"
},
"source_control": {
"origin": {
"credentials": "", // This is required. Leave blank like this if using SSH
"path": "clusters/production-system-1",
"reference": "refs/heads/main",
"ssh_credentials": {
"passphrase": "passphrase_id",
"private_key": "ssh_key_id"
},
"url": "https://github.com/org/repo"
}
}
}

Update an existing system

Endpoint: PUT v1/systems/{system}

Doc: https://square.styra.com/v1/docs/redoc.html#operation/UpdateSystem

Example parameters:

{
"system": "xn7ndpgbtm5irndphlrk1bzslbszyblp",
"name": "production-system-1",
"type": "kubernetes",
"deployment_parameters": {
"kubernetes_version": "1.17"
},
"source_control": {
"origin": {
"credentials": "", // This is required. Leave blank like this if using SSH
"path": "clusters/production-system-1",
"reference": "refs/heads/main",
"ssh_credentials": {
"passphrase": "passphrase_id",
"private_key": "ssh_key_id"
},
"url": "https://github.com/org/repo"
}
}
}