Getting Started

Last updated 2 months ago

Everything you need to know to get started with SlashDeploy.

Overview

‚ÄčSlashDeploy is a Web app built on top of GitHub Deployment API and Slack. In a nutshell, SlashDeploy receives your commands from Slack /deploy slash command, creates deployments on GitHub, listens to the GitHub deployment updates and notifies your team about deployments on Slack.

SlashDeploy does not really execute deployments on its own. We leverage GitHub Deployment API to let you listen for GitHub deployment events yourself and run deployments on the infrastructure you wish. By decoupling the act of requesting a deployment, and the actual fulfillment, this allows you to have a consistent interface for performing deployments, whether it's a web app, mobile application or 3rd party system.

Additionally, that makes it possible for us not to require access to your servers, nor the source code and play nicely with other CI/CD tooling you might be using, hence, leaving you with full control over your data and infrastructure.

Installing

Installing SlashDeploy is as simple as using our Add to Slack button. Clicking it, will enable /deploy command in your Slack team, as well as add a @slashdeploy bot user. The Slack bot is used to send you direct messages about deployment statuses.

After you've added SlashDeploy to your Slack team, you will be redirected to our GitHub App to grant access to repositories you want to deploy with SlashDeploy. It's important to note, that the app is configured on per-repository basis and we never clone, nor access your source code. We require a number of permissions to be able to receive GitHub Push events, in order to trigger auto-deployments.

Configuring

SlashDeploy deployment configuration is managed alongside your code. Simply drop a .slashdeploy.yml file under the root for your GitHub repository and SlashDeploy will pick up the changes.

To start off, add this sample configuration file and push it to GitHub:

.slashdeploy.yml
version: 1
environments:
production:
aliases:
- prod
checks:
- ci/circleci
auto_deploy:
ref: refs/heads/master

Feel free to replace required status checks with any other services you use in your deployment pipeline. Remove auto-deploy configuration, if you want to disable auto-deployments for now. If you're enforcing GitHub Branch protection rules, you should probably use the same set of Require status checks.

For a complete list of available configuration settings, see our .slashdeploy.yml reference guide.

You're all set now to run your first /deploy command!

Deploying

Once SlashDeploy is installed and .slashdeploy.yml configuration file is in place, you can start operating the /deploy command, which brings you the first-hand experience to managing your deployments from Slack.

The first time you run /deploy command, you will be asked to authenticate with GitHub, so that SlashDeploy could create deployments on behalf of your GitHub account.

Go ahead, and try deploying one of the repositories you linked earlier, for example:

/deploy acme/api to production

If you've configured environment aliases, you can deploy with a shortcut, for example:/deploy acme/api to prod

For a complete list of available deploy commands, see our Commands reference guide.

What's next?

Now that you can request GitHub deployments from Slack, you will need to set up your infrastructure to fulfill them. Although, this process varies greatly from one organization to another and far beyond the scope of this document, we've prepared a GitHub Deployments document with some general guidelines and recommendations.