zine/issues/3/001-drone-1.md

a fistful of drones

author: terris

Using drone in the tildeverse, part 1

A verbose introduction to using drone CI on the tildeverse for beginners, written by a total noob.

This is a short and wordy introduction to using drone with tildegit.org to do stuff to repositories when you push changes to them. This can be used to build and test a project or to deploy some web pages, like we see here.

When you are logged into tildegit's gitea web interface, you can visit drone.tildegit.org and select which of your repositories you'd like to activate for use with drone.

After the repository is activated for use with drone, drone will only know what do when there is a .drone.yml file present in the root directory of the repository.^[a different filename may be specified in drone's web interface]

This zine is now deployed using drone.

The zine's .drone.yml as of this writing, annotated:

---
kind: pipeline
type: ssh
name: deploy

The --- at the beginning, indicates that what follows is a yaml block. The next 3 lines begin the definition of what kind of stuff drone will do with this repository. More info about what's possible here can be found in drone's documentation, but these here tell us that drone is going to use ssh in a job named deploy.

This ssh pipeline will log into a server as a user you specify (most likely your own user account) and will do stuff you specify. Be careful!

server:
    host:
        from_secret: host
    user:
        from_secret: username
    ssh_key:
        from_secret: ssh_key

This part of the block specifies the server and account that drone will be connecting to using ssh the indented from_secret: lines specify that drone will be filling in these fields from its per-repository settings so to use something like this, you would create an entry for each of these secrets in the drone web interface. You could skip the secrets loading, but this is not a good idea, since they would be visible in your repository.

It is recommended to create a separate ssh key that you would use just with drone.

You would create the keys in your ~/.ssh/ directory, and add the keyname.pub to your ~/.ssh/allowed_keys file. the private key ~/.ssh/keyname, you would paste into the drone interface for the ssh_key variable above.

clone:
    disable: true

Typically a drone pipeline will clone your repository to its workspace before doing other stuff. In this case, this step is not necessary, since the commands below will do just that, but in a more useful place for this application.

trigger:
    branch:
        - master

This trigger definition above, says that drone will do its thing when changes are pushed to the master branch of the repository. Many trigger options are possible.

steps:
    - name: deploy
      commands:
          - cd /var/www/zine.tildeverse.org
          - sudo -Hu www-data git pull origin master
    - name: build
      commands:
          - cd /var/www/zine.tildeverse.org
          - make all

This part of the yaml block specifies the steps that drone will perform. These steps are usually performed inside the workspace clone of your repository but in this case the workspace doesn't contain a clone of the repository because of the specification above. Each step can be named, and can contain multiple commands. Drone builds shell scripts around these commands, so they are performed as the username on the host specified among secrets above.

The steps outlined here first change to the /var/www/zine.tildeverse.org directory, and then pull the repository into that directory as the user www-data and then runs make in that directory so that it proceeds to build the zine according to the Makefile^[previously: Makefile Magic @ zine issue-2] in the repository.