Merge pull request #27 from runwaylab/docs

Update documentation

docs/deployments.md

@@ -1,3 +1,88 @@
 # Deployments
 
-TODO
+Deployments are triggered by events and define how your "project" gets deployed. Deployments are generally commands that runway executes.
+
+This document goes over the different types of deployments that runway can handle for and how to configure them.
+
+All event example configurations assume that you are extending an example configuration like this one:
+
+```yaml
+projects:
+  - name: project-1
+    # this is the relevant part for this page
+    deployment: # the deployment configuration to run when an event is triggered (only one deployment per project)
+      # details in each section below
+    events:
+      # ...
+```
+
+## Command Deployment
+
+Command deployments are the only deployment types supported currently. They run a command on the **local** machine or **remote** server (via SSH). Runway will execute the command using the specified entrypoint and arguments.
+
+A very helpful feature of command deployments is the `success_string` field. This field allows you to specify a string that runway will look for in the output of the command. If the string is found, the deployment is considered successful. If the string is not found, the deployment is considered a failure.
+
+### Local
+
+Local commands are executed directly on the host by runway. This is useful for running commands that don't require a remote connection (SSH).
+
+If you are running runway from within a docker container, the host will literally be the container that runway is running in.
+
+If you are running a binary of runway on your local machine, the host will be your local machine.
+
+Usage:
+
+```yaml
+type: command # this deployment type runs a command on the local machine or remote server (via SSH)
+location: local # run the command on the local machine
+path: foo/bar # local path to run the command in
+timeout: 300 # the maximum time in seconds that a cmd can run before it is killed and the deployment fails - default is 300
+entrypoint: bash # the command/binary/entrypoint - like docker syntax!
+cmd: ["-c", "echo 'hello world' > test-example.txt"] # the command to run using the entrypoint - like docker syntax!
+```
+
+### Remote
+
+Remote commands are executed on a remote server via SSH. This is useful for running commands on a server that runway has access to.
+
+For example, you could use this to deploy a new version of your application to a server that you have SSH access to.
+
+Usage:
+
+```yaml
+type: command # this deployment type runs a command on the local machine or remote server (via SSH)
+location: remote # run the command on a remote server via SSH
+remote: # configuration block to establish an SSH connection to the remote server
+  auth: publickey # the authentication method to use (`login`, `publickey`, or `agent`)
+  host: 'server.example.com' # the hostname or IP address of the remote server
+  port: 22 # the port to connect to on the remote server
+  username: ubuntu # the username to use to connect to the remote server
+  public_key_path: /runway/keys/id_rsa.pub # the path to the public key to use for authentication (must be accessible to runway)
+  private_key_path: /runway/keys/id_rsa # the path to the private key to use for authentication (must be accessible to runway)
+success_string: complete-remote # the string to look for in the output of the command to determine if the deployment was successful
+timeout: 5 # the maximum time in seconds that a cmd can run before it is killed and the deployment fails - default is 300
+entrypoint: bash # the command/binary/entrypoint - like docker syntax!
+cmd: ["-c", "'echo path: {{ payload.path }} > /app/logs/result-remote.txt && echo complete-remote'"] # the command to run, wrap it in single quotes because character escaping is hard :(
+```
+
+The following remote connection types are supported:
+
+- `login`: Use a username and password to connect to the remote server
+- `publickey`: Use a public/private key pair to connect to the remote server (yeah you need to provide both keys because the underlying library is weird)
+- `agent`: Use an SSH agent to connect to the remote server
+
+Note: If you are using `publickey` authentication, you will need to provide both the public and private key paths. These key paths must be accessible to runway. If you are running runway from within a docker container, you will need to mount the keys into the container. Please also review the [known issues](./known-issues.md) document to ensure that you have the correct permissions set on your keys.
+
+### Payload Interpolation
+
+You can use the `{{ payload.key }}` syntax to interpolate values from the payload into your command. This is useful for passing data from an event into a deployment.
+
+The full list of `payload` attributes that _might_ be available to use can be found [here](../src/runway/models/deployment_payload.cr). The reason that we say "might" is because the payload is event-specific and not all events will have the same payload attributes set. For example, a `github_deployment` event will have different payload attributes than a `file` event. A GitHub deployment event will have `repo`, `environment`, and `sha` / `ref` attributes, while a file event will not
+
+This can be incredibly useful for passing data from an event into a deployment. For example, you could do something like this for your remote deployment command:
+
+```yaml
+cmd: ["-c", "'script/deploy --ref {{ payload.ref }}'"]
+```
+
+This would pass the `ref` attribute that was set from the `github_deployment` event into the `script/deploy` script on the remote server. Pretty neat!

docs/events.md

@@ -1,3 +1,59 @@
-# Events
+# Events 🕒
 
-TODO
+Events are "things" that runway looks for which trigger deployments. This document goes over the different types of events that runway can look for and how to configure them.
+
+All event example configurations assume that you are extending an example configuration like this one:
+
+```yaml
+projects:
+  - name: project-1
+    deployment:
+      type: command
+      location: local
+      path: foo/bar/
+      timeout: 5
+      entrypoint: bash
+      cmd: ["-c", "echo 'success'"]
+    events:
+      # this is the important part right here! this is the section that this page is all about
+      # you can have any number of events here, just make sure they are properly indented...
+      # ... and you follow the docs for the event type you are using, which you can find on this page below
+      - type: example # this is what each section will document on this page!
+      # ...
+```
+
+## File Event
+
+The file event is an incredibly simple event that looks for the existence of a file in a directory. When the file is found, runway will trigger a deployment.
+
+> This event is mostly just used for unit and acceptance testing purposes within this project
+
+Usage:
+
+```yaml
+type: file
+path: acceptance/projects/project-2/ship-it.txt # the path to the file to look for
+cleanup: true # remove the file after the event (true or false)
+schedule:
+  interval: 3s # how often to check for the file
+```
+
+## GitHub Deployment Event
+
+GitHub deployment events look for a specific environment that has been deployed on GitHub ([learn more about deploying environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment)). This event runs on a schedule and looks for the most recent deployment in the specified environment and checks to see if it is in the `in_progress` state. If it is, it triggers a deployment event.
+
+The most common use case for this event type, is to look for and complete branch-deploy workflows that are triggered via IssueOps in GitHub Actions. Here is a [live example](https://github.com/GrantBirki/pihole/blob/38b9c166ebb2ea216453b9cf804fee87ad5f853b/.github/workflows/branch-deploy.yml).
+
+By using this event type, you can tell `runway` to periodically check a given repo + environment for a deployment in progress and trigger a deployment when it finds one to complete it.
+
+Usage:
+
+```yaml
+type: github_deployment # github deployment event
+repo: runwaylab/test-flight # the GitHub repository to check for deployment events
+environment: production # the specific GitHub environment to check for
+deployment_filter: 1 # only look at the most recent deployment (based on the created_at field) - this field is required only for the github_deployment type event. It helps to save on API requests to GitHub. If not provided, it defaults to 1
+schedule:
+  interval: 3s # intervals can be in milliseconds, seconds or minutes (ms, s, or m) - or a cron expression
+  timezone: UTC # the timezone to use for the schedule (default is UTC) - ex: Europe/Berlin or America/New_York - see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+```