Stevenson is a Vapor framework designed to build integrations between Slack apps, GitHub, JIRA and CI services (CircleCI).
Stevenson
is a Vapor framework designed to build integrations between Slack apps, GitHub, JIRA and CI services (CircleCI).
This project also contains implementation of the Slack app used by Babylon iOS team (if you want to know more about how our team works, check our playbook)
To use Stevenson
in your app add it as a dependency to your Package.swift
:
dependencies: [
.package(url: "https://github.com/babylonhealth/Stevenson.git", .branch("master")),
]
and then import it to your project:
import Stevenson
Stevenson
comes with implementation of Slack slash commands, GitHub, JIRA and CircleCI APIs. At the moment it does not implement complete set of these APIs but only provides bare minimum required for the functionality of the app.
To create these services, use corresponding type constructors providing required values. It's advised but not required to store these values in the environment variables:
let slack = SlackService(
token: Environment.get("SLACK_TOKEN")
)
let ci = CircleCIService(
token: Environment.get("CIRCLECI_TOKEN")
)
let jira = JiraService(
baseURL: Environment.get("JIRA_BASE_URL").flatMap(URL.init(string:)),
username: Environment.get("JIRA_USERNAME"),
password: Environment.get("JIRA_TOKEN")
)
let github = GitHubService(
username: Environment.get("GITHUB_USERNAME"),
token: Environment.get("GITHUB_TOKEN")
)
To create a Slack slash command start with registering it in your Slack app following Slack documentation.
Note: instead of using your own Slack app you may use Slack Slash Commands app. In this case you will register your slash commands in this app but the process will be pretty much the same.
Then use the SlackCommand
type to implement it:
let myAmazingCommand = SlackCommand(
// This name should be the same name that you used to register a command in your Slack app
name: "myAmazingCommand",
// This message will be sent back to Slack when you call your command with `/myAmazingCommand help`
help: "Some command usage instructions",
// This closure is where the command is actually implemented
run: { metadata, request in
/**
Parse `metadata` here, do something useful,
i.e. invoke a CI job, and send a response back to Slack
*/
}
)
Then register a route in your app with a path that matches the command name (usually Slack sends commands as POST
requests):
router.post(myAmazingCommand.name) { request -> Future<Response> in
try slack.handle(command: myAmazingCommand, on: request)
}
For more details check the commands implemented in the app.
To develop locally on this repo:
vapor xcode
to create the Xcode projecthttp://localhost:8080
For example to simulate /fastlane somelane someargs
, use this (adapt the &text=
value and the /fastlane
endpoint to your needs)
curl --request POST \
--url http://localhost:8080/fastlane \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'token=__SLACK_TOKEN__&channel_name=__SOME_SLACK_CHANNEL__&text=somelane%20someargs'
If you need to create a new Slack command:
https://api.slack.com/apps/<YourSlackAppID>/slash-commands
/foo
)https://<appname>.herokuapp.com/<command>
, replacing <appname>
with the name of your Heroku app instance (e.g. stevenson-bot
) and <command>
by the command name (e.g. foo
)extension SlackCommand
(see MainCommand.swift
or SlackCommand+Fastlane
as examples):extension SlackCommand {
static func <command>(/* optional params if needed */) {
SlackCommand(
name: "<command>",
help: "...",
allowedChannels: [...],
run: { ... }
)
}
}
configure.swift
and add that newly-created command to the list of handled commandsroutes(router: router, slack: slack, commands: [
.fastlane(ci),
...,
.<command>()
])
There are just example instructions if you plan to host the app on Heroku.
You can skip step 1 and 2 if you have already set it up locally.
Install the Heroku CLI.
brew install heroku/brew/heroku
heroku login
Navigate to the local repo, and configure the Heroku remote using the CLI.
heroku git:remote -a <heroku-app-name>
Push the master
branch to deploy.
git checkout master
git push heroku master
Alternatively, you can deploy a specific branch manually by going to the deploy page on Heroku dashboard and using the "Manual Deploy" section at the very bottom.
Once the app is deployed, if you need to debug things, you can see the logs using heroku logs -a <heroku-app-name>
.
To set the aforementioned environment variables with the real values on Heroku:
SLACK_TOKEN
etc