How it works

Deliverybot is built around the GitHub deployments api. It’s an event driven decoupled way to deploy your code. Deliverybot is responsible for figuring out when to trigger a deployment. When conditions are met it triggers a deploy to the environment that you’ve specified in the configuration file. Once the deployment is triggered, your code picks up the deployment event and runs the actual deploy to your infrastructure.

The diagram below details what a deployment looks like:

+-------------+         +--------+         +----------------+        +-------------+
| Deliverybot |         | GitHub |         | GitHub Actions |        | Your Server |
+-------------+         +--------+         +----------------+        +-------------+
     |                      |                       |                     |
     |  Create Deployment   |                       |                     |
     |--------------------->|                       |                     |
     |                      |                       |                     |
     |  Deployment Created  |                       |                     |
     |<---------------------|                       |                     |
     |                      |                       |                     |
     |                      |   Deployment Event    |                     |
     |                      |---------------------->|                     |
     |                      |                       |     SSH+Deploys     |
     |                      |                       |-------------------->|
     |                      |                       |                     |
     |                      |   Deployment Status   |                     |
     |                      |<----------------------|                     |
     |                      |                       |                     |
     |                      |                       |   Deploy Completed  |
     |                      |                       |>--------------------|
     |                      |                       |                     |
     |                      |   Deployment Status   |                     |
     |                      |<----------------------|                     |
     |                      |                       |                     |

The benefit to this architecture is that your deployments are separate from the platform that you are deploying to. If you change platforms or use multiple platforms within a team you can still enforce the same continous delivery processes.

This architecture is well suited for GitHub Actions which is the GitHub supported system for running your code in response to GitHub events. It means that setting up Deliverybot is much simpler since you don’t also have to manage infrastructure to listen to events. The next sections go through guides on how to deliver deployments.

Deliverying deployments with GitHub actions

GitHub actions are one of the simplest ways to handle your deployments. Actions run on GitHub infrastructure in response to GitHub events. The basic format for setting up a GitHub action to handle a deployment looks like this:

# .github/workflows/deploy.yml
name: 'Deploy'
on: ['deployment']

jobs:
  deployment:
    runs-on: 'ubuntu-latest'
    steps: []
    # Steps to execute your deployment.

The above instantiates a workflow that will run on deployment events triggered in your specific repository. Deliverybot triggers these events and your code does the work of shipping the actual deployments onto your infrastructure.

If you are building your own actions, one important thing that you may notice is that the deployment is always sitting in ‘pending’ or ‘waiting’. For GitHub and Deliverybot to be able to track your deployment you need to send back deployment_status events. Below is a template for doing just that, we have actions that run before and after your main deployment block which set the correct status:

# .github/workflows/deploy.yml
name: 'Deploy'
on: ['deployment']

jobs:
  deployment:
    runs-on: 'ubuntu-latest'
    steps:
    - name: 'Checkout'
      uses: 'actions/checkout@v1'

    - name: 'Deployment pending'
      uses: 'deliverybot/deployment-status@master'
      with:
        state: 'pending'
        token: '$'

    - name: 'Deploy $'
      run: |
        echo 'YOUR CODE HERE'

    - name: 'Deployment success'
      if: success()
      uses: 'deliverybot/deployment-status@master'
      with:
        state: 'success'
        token: '$'

    - name: 'Deployment failure'
      if: failure()
      uses: 'deliverybot/deployment-status@master'
      with:
        state: 'failure'
        token: '$'

Deliverying deployments with external tooling

Since it’s just listening to GitHub events to execute a deployment you can use a wide variety of tooling to actually ship deployments. The following guide includes details on how to write code to handle deployments:

https://developer.github.com/v3/guides/delivering-deployments/

Need help? [email protected]
Or chat with the community on Spectrum