Managing SSH Keys

1. Adding SSH Keys to Project

Field	Description	Value
key	SSH private key content (PEM format)	`-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----`
fingerprint	SHA256 fingerprint of the public key	`abc123def456...`

Example: Adding SSH Key via CircleCI Web UI

circleci project ssh-key add <project-slug> <path-to-private-key>

Note: The private key must be in PEM format and not encrypted with a passphrase.

Warning: Never commit SSH keys to version control. Use CircleCI's encrypted environment variables or project settings.

2. Using add_ssh_keys Step

Parameter	Description	Default
add_ssh_keys	Enables SSH access to the build environment	false

Example: Enabling SSH access

version: 2.1
jobs:
  build:
    steps:
      - add_ssh_keys

Note: The add_ssh_keys step is required to enable SSH access in CircleCI builds.

Warning: SSH keys are stored in an encrypted format and should not be exposed in logs or configuration files.

3. Specifying Key Fingerprints

Field	Description	Example
fingerprint	SHA256 fingerprint of the SSH key	`sha256:abc123def456...`
key	Public key content (base64 encoded)	`AAAAB3NzaC1yc2EAAAADAQABAAABAQC...`

Example: Adding SSH Key with Fingerprint

version: 2.1
jobs:
  build:
    steps:
      - add_ssh_keys:
          fingerprints:
            - "sha256:abc123def456..."

4. Using Deploy Keys

Property	Description	Value
deploy_key	SSH key used for deployment to external services	`~/.ssh/deploy_key`
type	Key type (e.g., RSA, ECDSA)	`rsa`
fingerprint	SHA256 fingerprint of the key	`SHA256:abc123...`

Example: Adding Deploy Key to CircleCI Project

circleci project add-deploy-key <project-slug> <key-path>

Note: Deploy keys are used for read-only access to repositories or external services.

Warning: Ensure deploy keys are stored securely and not committed to version control.

5. Using User Keys

Property	Description	Value
circleci ssh user key	Command to manage SSH user keys	`circleci ssh user key`
circleci ssh user key list	List all SSH user keys	`circleci ssh user key list`
circleci ssh user key add	Add a new SSH user key	`circleci ssh user key add <key-path>`
circleci ssh user key remove	Remove an SSH user key	`circleci ssh user key remove <key-fingerprint>`

Example: Adding an SSH User Key

circleci ssh user key add ~/.ssh/id_rsa.pub

Example: Listing SSH User Keys

circleci ssh user key list

Note: User keys are used to securely connect to your project's build environment via SSH. Ensure the key is added to CircleCI before attempting to connect.

6. Configuring SSH for Git Operations

Option	Values	Description
checkout_key	`ssh`	Enables SSH key checkout for Git operations
git_clone_depth	`0`	Full clone depth (default: 0 for full clone)

Example: SSH Key Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Setup SSH
          command: |
            mkdir -p ~/.ssh
            echo "$SSH_KEY" > ~/.ssh/id_rsa
            chmod 600 ~/.ssh/id_rsa
            ssh-keyscan github.com >> ~/.ssh/known_hosts

Note: Ensure the SSH key is added to CircleCI context or environment variables.

Warning: The SSH key must have appropriate permissions to access the repository.

7. Using SSH for Remote Servers

Option	Values	Notes
ssh.key	`circleci-ssh-key`	SSH key name used for remote server access
ssh.host	`example.com`	Remote server hostname or IP address
ssh.port	`22`	SSH port (default is 22)
ssh.user	`circleci`	User account on remote server

Example: SSH Configuration in CircleCI

version: 2.1
jobs:
  deploy:
    docker:
      - image: circleci/python:3.9
    steps:
      - checkout
      - run:
          name: Deploy via SSH
          command: |
            ssh -o StrictHostKeyChecking=no circleci@example.com "cd /app && ./deploy.sh"

Note: Ensure SSH keys are added to CircleCI context or project settings for secure access.

Warning: Avoid using StrictHostKeyChecking=no in production environments.

8. Managing Multiple SSH Keys

Key Name	Usage	Notes
circleci-ssh-key-1	Used for accessing private repositories or servers	Generated automatically during project setup
circleci-ssh-key-2	For deployment to staging environments	Can be added manually via CircleCI UI or API
circleci-ssh-key-3	For production server access	Requires approval from team lead before adding

Example: Adding SSH Key to Project

circleci ssh add-key --key-name circleci-ssh-key-2

Note: Ensure that each SSH key has appropriate permissions and is securely stored in CircleCI's encrypted environment variables.

Warning: Never commit SSH keys to version control. Always use CircleCI's secure key management features.

9. Rotating SSH Keys

Step	Description	Action
1	Generate a new SSH key pair	`ssh-keygen -t rsa -b 4096 -C "circleci@yourdomain.com"`
2	Copy the public key to your clipboard	`cat ~/.ssh/id_rsa.pub \| pbcopy`
3	Add the new public key to your CircleCI project settings	`circleci project set-ssh-key <project-slug> ~/.ssh/id_rsa.pub`
4	Update your CircleCI configuration to use the new key	`version: 2.1 jobs: build: steps: - checkout: ssh-key: "new-ssh-key"`
5	Remove the old SSH key from CircleCI project settings	`circleci project remove-ssh-key <project-slug> <old-key-fingerprint>`

Note: Ensure that all team members have updated their local SSH configurations to use the new key before removing the old one.

10. Debugging SSH Issues

Issue	Possible Cause	Solution
Connection timeout	Firewall or network configuration blocking SSH port (22)	Check network ACLs and ensure port 22 is open for inbound connections
Permission denied (publickey)	Incorrect or missing SSH key in CircleCI project settings	Verify the SSH key is added to the project's SSH keys in CircleCI settings
Host key verification failed	New or changed host key not recognized by CircleCI	Update known_hosts file in the project or use strict host key checking off
SSH agent not running	CircleCI job cannot access SSH keys via agent	Start the SSH agent and add keys using `eval "$(ssh-agent -s)"` and `ssh-add ~/.ssh/id_rsa`

Example: SSH debug command in CircleCI config

steps:
  - run:
      name: Debug SSH connection
      command: |
        set -x
        ssh -v -o StrictHostKeyChecking=no user@hostname "echo 'Connected successfully'"

Note: Use -v flag for verbose SSH output to help identify where the connection fails.

Warning: Avoid using StrictHostKeyChecking=no in production environments as it makes the system vulnerable to man-in-the-middle attacks.