SSH

note
The SSH executor supports only scripts generated in Bash and the caching feature is currently not supported.

This is a simple executor that allows you to execute builds on a remote machine by executing commands over SSH.

note
GitLab Runner will use the git lfs command if Git LFS is installed on the remote machine. Ensure Git LFS is up-to-date on any remote systems where GitLab Runner will run using SSH executor.

Overview

To use the SSH executor you need to specify executor = "ssh" under the [runners.ssh] section. For example:

[[runners]]
  executor = "ssh"
  [runners.ssh]
    host = "example.com"
    port = "22"
    user = "root"
    password = "password"
    identity_file = "/path/to/identity/file"

You can use password or identity_file or both to authenticate against the server. GitLab Runner doesn’t implicitly read identity_file from /home/user/.ssh/id_(rsa|dsa|ecdsa). The identity_file needs to be explicitly specified.

The project’s source is checked out to: ~/builds/<short-token>/<concurrent-id>/<namespace>/<project-name>.

Where:

  • <short-token> is a shortened version of the runner’s token (first 8 letters)
  • <concurrent-id> is a unique number, identifying the local job ID on the particular runner in context of the project
  • <namespace> is the namespace where the project is stored on GitLab
  • <project-name> is the name of the project as it is stored on GitLab

To overwrite the ~/builds directory, specify the builds_dir options under [[runners]] section in config.toml.

If you want to upload job artifacts, install gitlab-runner on the host you are connecting to via SSH.

Security

Introduced in GitLab 14.3.

To enable SSH StrictHostKeyChecking, make sure the [runners.ssh.disable_strict_host_key_checking] is set to false. The current default is true.

In GitLab 15.0 and later, the default value will be false, meaning host key checking is required.

We are not setting the value to false immediately, because we don’t want to break existing builds.