Table Of Contents

Preparations

To make a Pipeline that runs your build steps on a remote machine via SSH you need the following:

Requirements

To check if the SSH Runner is working you can check the docker container logs, as it runs a ping check to the configured Server to see if Drone CI is reachable:
time="2021-07-30T07:00:25Z" level=info msg="starting the server" addr=":3000"
time="2021-07-30T07:00:25Z" level=info msg="successfully pinged the remote server"
time="2021-07-30T07:00:25Z" level=info msg="polling the remote server" capacity=10 endpoint="http://192.168.0.12:8085" kind=pipeline type=ssh

Generate SSH Key Pair

If you want to Authenticate with a Key Pair:

Generate the Key Pair for the User you want to use for the Builds:

ssh-keygen -t rsa -f id_droneci -C droneci@testerver

# add the Public Key to .ssh/authorized_keys
cat id_droneci.pub >> /home/droneci/.ssh/authorized_keys

We will store the Private Key later in the Drone Secrets Vault.

Pipeline Configuration File .drone.yml

Now, as the first step we need to create a Configuration File called .drone.yml to the Repository so that Drone knows what to do (For further Infos check the Docs):

Staging

Add these lines first to .drone.yml where “name” is the Name of a Pipeline Stage, which later gets shown on the Drone Dashboard and the Stage Type is “ssh”.

An advanced Pipeline can also have multiple Pipeline Stages with Conditions, each with multiple Steps. For this Tutorial we keep it simple though.

---
kind: pipeline
type: ssh
name: Tutorial

Server

Now the Configuration for the SSH Connection: we can either use a Password or a Key Pair for the Authentication. I recommend storing the Password/Key in the Secrets Vault on the Drone Server (we will come to that later). You can check out the Docs for all options. For my Purposes I will use a Key Pair stored in the Secrets Vault with the Name “rsa_key”.

server:
  host: testerver
  user: droneci
  ssh_key:
    from_secret: rsa_key

(optional) Cloning via ssh instead of http/https

Normally Drone CI clones the Repositories via http/https. If you want to clone via SSH you need to first pass your SSH Private Key as an Environment Variable (KEY) and then add it to the .ssh Directory. In this example I already stored the Key with the name ssh_key as a Secret in Drone. Give it a fitting Name here, we will later store the Private Key in the Secret Vault inside Drone with the same Name.

Disable the default HTTP/S Cloning Routine and add a custom Cloning Step that adds the Private Key to the .ssh Directory and then clones to the current Directory:

Make sure the Public Key is known to the Git Server.
clone:
  disable: true

steps:
  - name: clone
    environment:
      KEY:
        from_secret: ssh_key
    commands:
      - echo "$KEY" > $HOME/.ssh/id_git_rsa
      - git clone ssh://git@your.gitserver.com:22/USERNAME/REPOSITORY.git .
      - git checkout $DRONE_COMMIT

Steps

Finally we add the Build Steps to the File. Every Step has a Name and at least one Command, which will be run one after another very similar as in a simple Shell Script.

If you already added the code for cloning with SSH you need to skip the first line that contains “steps:”, as it is only required once.

steps:
  - name: Show Environment
    commands:
      - whoami
      - pwd
      - hostname

  - name: Run Test Script
    commands:
      - ./test.sh
Note that Steps will by default fail if a Command or Script exits with anything higher than 0.

Final File

At the end the file will look like this:

---
kind: pipeline
type: ssh
name: Tutorial

server:
  host: testerver
  user: droneci
  ssh_key:
    from_secret: rsa_key

clone:
  disable: true

steps:
  - name: clone
    environment:
      KEY:
        from_secret: ssh_key
    commands:
      - echo "$KEY" > $HOME/.ssh/id_git_rsa
      - git clone ssh://git@your.gitserver.com:22/USERNAME/REPOSITORY.git .
      - git checkout $DRONE_COMMIT

  - name: Show Environment
    commands:
      - whoami
      - pwd
      - hostname

  - name: Run Test Script
    commands:
      - ./test.sh

Push Changes

Finally push the .drone.yml

git add .drone.yml
git commit -m "add drone ci configuration"
git push

Activate the Repository for Builds

If you login on your Drone Server for the first time it will redirect you to your Git Service to authenticate yourself there first. After that you should now see all your Repositories listed on the Drone Dashboard, if not click the "Sync"-Button on the top right corner.

Select the Repository you want to create Builds for and click “Activate Repository”.

Add the Build Secrets

Now we need to add the Build Secrets we specified in the Pipeline Configuration File:
On the Drone Dashboard select your Repository, then change to Settings > Secrets.
Click “New Secret” and enter the same Name used for the Password or Key in the .drone.yml.

Password

If you use a Password just enter it in the Value-Field and click Create.

Key Pair

Copy the Private Key of your previously generated Key Pair in the Value-Field in click Create.

Final Steps

Now the Drone CI Pipeline wil run whenever you push a Commit to Repository (default setting is on the master Branch) or when you press “New Build” in the top right corner.