# a fistful of drones

author: [terris](https://terris.tilde.team/)

## 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](https://drone.io/) with
[tildegit.org](https://www.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](https://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](https://tildegit.org/tildeverse/zine/src/branch/master/.drone.yml)
as of this writing, annotated:


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

```

The `---` at the beginning, indicates that what follows is a
[yaml](https://yaml.org/) 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](https://docs.drone.io/configure/secrets/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](https://tilde.team/wiki/ssh#linux) 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](https://ssh-runner.docs.drone.io/configuration/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](https://ssh-runner.docs.drone.io/configuration/trigger/) 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](https://ssh-runner.docs.drone.io/configuration/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](https://tildegit.org/tildeverse/zine/src/branch/master/Makefile)^[previously:
[Makefile Magic @ zine issue-2](https://zine.tildeverse.org/issue-2.html#makefile-magic)] in
the repository.