Warning

As SlashDeploy is still in beta, the documentation here is subject to change and some parts may be incomplete. If you have feedback, please send it to hi@slashdeploy.io.

Installation

The easiest way to install SlashDeploy is to use our Add to Slack button:

Add to Slack

This allows us to automatically install the /deploy command as well as a @slashdeploy bot user, which is used to send you notifications when deployments start and end.

Slash Command

Once SlashDeploy is installed into your Slack team, you'll have access to the /deploy command. The first time you type /deploy you'll be asked to authenticate with GitHub so that SlashDeploy can create GitHub Deployments on your behalf.

Deploying

To deploy the default ref (master) to the default environment (production).

/deploy acme-inc/api

To deploy the default ref (master) to a different environment.

/deploy acme-inc/api to staging

To deploy a branch (or git sha, or git tag) to the default environment.

/deploy acme-inc/api@branch

By default, all GitHub commit statuses will be checked before creating a deployment, you can disable this check by using the ! flag.

/deploy acme-inc/api@branch!

To find out what environments you can deploy the repo to.

/deploy where acme-inc/api

Locking

SlashDeploy also allows you to "lock" environments. If for example, I wanted to test a migration on the staging environment, I can lock it with a message.

/deploy lock staging on acme-inc/api: I'm testing a migration

If any of my other team members try to deploy to the staging environment, they'll see the lock message.

/deploy acme-inc/api to staging

When I'm done testing my changes, I can unlock the environment so others can deploy to it again.

/deploy unlock staging on acme-inc/api

When I'm done for the day, I can release all my locks.

/deploy unlock all

.slashdeploy.yml

You may configure SlashDeploy for your project by putting a .slashdeploy.yml file in the root of your git repository.

Here is a heavily commented .slashdeploy.yml example: 

---
# teach SlashDeploy which environment is default. optional.
# used when environment is not passed to a `/deploy` command.
default_environment: production

# a document of available environments for this repository.
environments:

  # an environment named "production".
  production:

    # an optional list of aliases used to refer to the "production" environment.
    aliases:
      - prod

  # another environment named "stage".
  stage:
    aliases:
      - staging
Continuous Delivery

You can configure SlashDeploy to automatically deploy a branch to an environment when you push code to GitHub.

If you utilize Github "Branch Protection Rules", you should likely use the same set of "Require status checks" under required_contexts.

This example .slashdeploy.yml file will automatically deploy the master branch to the production environment, once tests are passing on CircleCI:

---
environments:
  production:

    # Enable continuous delivery for this environment.
    continuous_delivery:

      # Specify any git "ref" (tag, branch, etc) to auto deploy when pushed to.
      ref: refs/heads/master
  
      # To deploy only after a set of GitHub commit statuses pass,
      # configure required_contexts (optional).
      required_contexts:
        - ci/circleci

FAQ
What's GitHub Deployments?
In a nutshell, GitHub Deployments are a way to initialize a deployment request for a GitHub repository. It allows you to decouple the act of requesting a deployment, and the actual fullfillment. This allows you to have a consistent interface for performing deployments, whether it's a web app, infrastructure, native application, etc.

How does SlashDeploy know who I am on GitHub?
When you first run the /deploy command, we ask you to authenticate with your GitHub account, which is then linked to your Slack user account.
Troubleshooting

Here we have some debugging information about the common issues and how to resolve them.

Error 1: The deployment did not start
If a deployment does not start in half a minute, you will get a Slack notification letting you know something went wrong. This might happen for a number of reasons, so check the following.
  • make sure the repo's .slashdeploy.yml file is configured properly
  • make sure the repo has a Github Deployment Integration (and Webhooks) to handle deployment events
  • make sure the service handling the deployment events is working and sending Deployment Status updates to Github
  • make sure the service handling the deployment events is not filtering or ignoring deployment requests. For example, it will deploy to production, however the provided environment in the deployment event was prod.
Error 2: A required commit status context is stuck in pending
Inside the repo's .slashdeploy.yml a list of required_contexts was defined which need to move into the success state in order to continue. For some reason, after about 1 hour of waiting, at least one of these required_contexts are stuck in the pending state instead of transitioning to success, failure, or error. If you fix this issue your deployment will likely continue.