126 lines
4.3 KiB
Markdown
126 lines
4.3 KiB
Markdown
|
# 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.
|
||
|
|
||
|
|