Working with SSH Debugging

1. Enabling SSH Access

CircleCI allows you to enable SSH access to running jobs for debugging purposes. This feature is particularly useful when troubleshooting issues in your build environment.

Setting	Description	Value
enable_ssh	Enables SSH access to the job container	`true`

Example: Enabling SSH in a CircleCI Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: npm install
      - run:
          name: Enable SSH
          command: echo "SSH enabled"

Note: SSH access is only available for jobs running on Linux containers.

Warning: SSH access is disabled by default for security reasons. It must be explicitly enabled in your configuration.

2. Connecting via SSH

Step	Description	Details
1. Enable SSH	Enable SSH access for a job	Set `enable_ssh: true` in the job configuration.
2. Start SSH Session	Start an SSH session to the job container	Use `circleci debug` command or SSH into the container using provided connection details.
3. Connect to Container	Use SSH to connect to the job container	Run `ssh -p <port> <user>@<host>` with the provided SSH details.

Example: Enabling SSH in a Job

jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install
      - <span class="badge badge--new">NEW</span> enable_ssh: true

Note: SSH access is only available for jobs running on CircleCI's infrastructure.

Warning: SSH access is disabled by default for security reasons.

3. Understanding SSH Session Limits

Limit Type	Value	Description
Concurrent Sessions	`1`	Only one SSH session is allowed per job
Session Duration	`1 hour`	SSH sessions timeout after 1 hour of inactivity
Connection Attempts	`3 attempts`	Maximum retry attempts before connection is blocked

Note: SSH access is disabled by default and must be enabled in the project settings.

Warning: Concurrent SSH sessions are not supported. Only one session per job is permitted.

4. Debugging Build Failures

Example: SSH into a Build Container

circleci debug

Step	Description	Notes
circleci debug	Initiates SSH debugging session	Requires project to be configured for SSH

Note: Ensure SSH is enabled in your CircleCI project settings to use this feature.

Example: Inspecting Environment Variables

echo $CIRCLE_JOB

Example: Running Commands in Debug Mode

circleci exec --job build

Common Build Failure Causes

Incorrect configuration in config.yml
Missing dependencies or environment variables
Timeouts during long-running operations
Permission issues in build containers

5. Inspecting Build Environment

Aspect	Description	Details
Environment Variables	Available variables in the build environment	`CIRCLECI=true CIRCLE_BUILD_NUM=123 CIRCLE_JOB=build CIRCLE_SHA1=abc123def456`
Working Directory	Current directory for the build process	`/home/circleci/project`
Installed Tools	Tools and versions available in the environment	`node v18.17.0, npm 9.6.7, python 3.10.12`

Example: Print Environment Variables

echo "Build number: $CIRCLE_BUILD_NUM"
echo "Current branch: $CIRCLE_BRANCH"
echo "Repository URL: $CIRCLE_REPOSITORY_URL"

Note: Use echo or printenv to inspect environment variables during a build.

Example: List Files in Working Directory

ls -la
find . -name "*.js" | head -5

6. Testing Commands Interactively

Example: SSH into a CircleCI Job

circleci debug

Command	Description	Notes
circleci debug	Initiates SSH debugging session	Must be run from project directory with CircleCI CLI installed

Note: The debug session will provide a temporary SSH key to connect to the job container.

Warning: SSH sessions are only available for jobs that support debugging. Jobs running in a container or with specific security settings may not allow SSH access.

7. Checking Environment Variables

Variable Name	Value	Description
CIRCLECI	`true`	Indicates that the build is running on CircleCI
CIRCLE_BUILD_NUM	`12345`	Unique identifier for the current build
CIRCLE_JOB	`build`	Name of the current job
CIRCLE_WORKFLOW_ID	`abc123def456`	Unique identifier for the current workflow
CIRCLE_SHA1	`5f4dcc3b5aa765d61900000000000000`	Git commit SHA of the current build
CIRCLE_BRANCH	`main`	Name of the Git branch being built
CIRCLE_TAG	`v1.0.0`	Git tag, if the build is for a tag
CIRCLE_USERNAME	`circleci-user`	Username of the CircleCI user who triggered the build

Example: Print All Environment Variables

echo "Build number: $CIRCLE_BUILD_NUM"
echo "Job name: $CIRCLE_JOB"
echo "Workflow ID: $CIRCLE_WORKFLOW_ID"
echo "Commit SHA: $CIRCLE_SHA1"

Note: Environment variables can be set in the CircleCI project settings or via configuration files like .circleci/config.yml.

8. Inspecting Installed Tools

Tool	Version Command	Description
Node.js	`node --version`	Displays the installed Node.js version
npm	`npm --version`	Displays the installed npm version
Python	`python --version`	Displays the installed Python version
Docker	`docker --version`	Displays the installed Docker version
Git	`git --version`	Displays the installed Git version
Java	`java -version`	Displays the installed Java version

Example: Check Node.js version

node --version

Example: List installed packages

npm list -g

9. Debugging Permission Issues

Issue	Description	Solution
SSH key permissions	SSH keys with incorrect permissions cause authentication failures.	Ensure keys have `600` permissions. Run `chmod 600 ~/.ssh/id_rsa`.
User permissions in config	CircleCI jobs may fail if the user lacks necessary permissions to execute commands.	Use `run` steps with appropriate user context or switch to root if needed.
File access in containers	Files or directories may not be accessible due to incorrect ownership or permissions.	Set proper ownership using `chown` and ensure `read`/`execute` permissions.

Example: Setting SSH key permissions

chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub

Note: Always verify SSH key permissions before initiating a debug session.

Warning: Incorrect permissions can lead to security vulnerabilities or job failures.

10. Extending SSH Session

Option	Values	Notes
ssh	`true`	Enable SSH access to the job container
enable_ssh	`true`	Alias for `ssh`, enables SSH debugging

Example: Enabling SSH in a CircleCI Job

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Install Dependencies
          command: npm install
      - ssh  # Enable SSH access to the job container