Bob is an extendable Slack bot written in Swift used to communicate with TravisCI and GitHub APIs. It's used to perform tasks of repetitive nature that cannot be fully automatized, such as creating release candidates for the App Store.
Simply send a message to Bob on Slack, and it will do the job for you.
Bob operates using commands. It comes with a couple of customizable commands, but new ones can easily be created. See creating custom commands for more information.
All commands are invoked by typing in {name} parameters.
For example:
build staging
could trigger a job on Travis that would create a build with staging configuration and distribute it to testers.
To see how a command should be used, type {name} usage
A dumy command that can be used to check if Bob is running. Simply say hello to Bob, and it will greet you back.
You can see which version of Bob is currently running by typing version
TravisScriptCommand is a configurable command that triggers a job on Travis and executes a script there. The command can have multiple targets that can be specified at runtime.
The script to run for each target is specified when the command is instantiated.
For example:
let buildTargets = [
TravisTarget(name: "staging", script: Script("fastlane ios distribute_staging")),
TravisTarget(name: "testflight", script: Script("fastlane ios distribute_testflight")),
]
let buildCommand = TravisScriptCommand(name: "build", config: travisConfig, targets: buildTargets, defaultBranch: "Develop")
try bob.register(buildCommand)would register a command with the name build. Typing build staging would start the lane distribute_staging on Travis.
iOS specific command used to change the CFBundleShortVersionString and CFBundleVersion values in specified .plist files.
For example:
let plistPaths: [String] = [
"App/Info.plist",
"siriKit/Info.plist",
"siriKitUI/Info.plist"
]
let alignCommand = AlignVersionCommand(gitHub: gitHub, plistPaths: plistPaths, author: author)
try bob.register(alignCommand)would register a command that can be invoked by typing align 3.0 4. Bob would then create a commit on GitHub by changing the 3 specified files.
iOS specific command used to increase the CFBundleVersion values in specified .plist files. Increases the build number by 1, if it is numeric.
For example:
let plistPaths: [String] = [
"App/Info.plist",
"siriKit/Info.plist",
"siriKitUI/Info.plist"
]
let bumpCommand = BumpCommand(gitHub: gitHub, plistPaths: plistPaths, author: author)
try bob.register(bumpCommand)would register a command that can be invoked by typing bump. Bob would then create a commit on GitHub by changing the 3 specified files.
Bob requires a Slack token in order to work. You can obtain one by creating a slack bot:
- Open the custom integration page
- Select
Bots - Type in a username for your bot.
bobthebuilderworks out nicely - Copy the
API Tokenfield. Bob will use this to connect to slack
Bob can be set up just as any other Swift Package, but since it relies on Vapor💧 we recommend setting it up with the Vapor toolbox. To install vapor toolbox you can follow the manual
Once you have the toolbox setup, you can start by creating a new project:
vapor new BobTheBuilder --template=n26/bob-vapor-template
cd BobTheBuilderAfter the template is cloned, the Package.swift should contain:
// swift-tools-version:4.0
import PackageDescription
let package = Package(
name: "BobTheBuilder",
dependencies: [
.package(url: "https://github.com/n26/bob", from: "1.0.0"),
],
targets: [
// The Commands target is the place to add any new custom commands
// When creating new commands, make sure that their Target Membership is set to `BobCustomCommands` and that they are public
.target(name: "BobCustomCommands", dependencies: ["Bob"]),
.target(name: "Run", dependencies: ["BobCustomCommands"])
// If you don't plan to implement any custom commands, you can have only one target
// .target(name: "Run", dependencies: ["Bob"])
]
)All of your custom code will reside in the Sources/BobCustomCommands folder.
Create an Xcode project by running
vapor xcodeOpen the Sources/Run/main.swift file configure the built-in commands or add yours. The minimal main.swift for starting Bob is
import Vapor
import Bob
// https://api.slack.com/apps
let config = Bob.Configuration(slackToken: "your-slack-token")
let drop = try Droplet()
let bob = Bob(config: config, droplet: drop)
try bob.start()and you're good to go. Select the Run scheme and run it. You can now send messages to Bob via Slack, and it will respond.
In order to use commands that communicate with the TravisCI API, you will need to provide a configuration. The configuration consists of
- Url of the repo on Travis. Along the lines of
https://api.travis-ci.com/repo/{owner%2Frepo} - Access token. You can obtain one by running
gem install travis && travis login && travis token
In order to use commands that communicate with the GitHub API, you will need to provide a configuration. The configuration consists of
- Your GitHub username
- A personal access token with read/write permissions. See this link on instructions how to generate one
- Url of the repo on GitHub. Alogn the lines of
https://api.github.com/repos/{owner}/{repo}
Bob supports sending multiple commands using 1 slack message. Just separate commands using | .
For example:
sync strings | align 3.0 5 | build staging | build testflightcould be used when creating a release candidate for the app store. It would update the strings on the repository, set the version and build the app for 2 environments
Custom commands can be created an provided to Bob. To create a command implement the Command protocol.
public protocol Command {
/// The name used to idenitfy a command (`hello`, `version` etc.). Case insensitive
var name: String { get }
/// String describing how to use the command.
var usage: String { get }
/// Executes the command
///
/// - Parameters:
/// - parameters: parameters passed to the command
/// - sender: object used to send feedback to the user
/// - Throws: An error is thrown if something goes wrong while executing the command, usualy while parsing the parameters
func execute(with parameters: [String], replyingTo sender: MessageSender) throws
}The actual work happens in the execute method. All of the parameters the user typed in will be passed to the method as [String]. To inform the user about progress of the command, call the send method on the sender object. It will send the message to the user via Slack. If any errors occur during the execution, simply throw them.
Bob comes with a subset of TravisCI and GitHub APIs written in swift.
Only contains a method to execute a script exposed via the TravisScriptCommand
Contains low level methods for manipulating files and trees on GitHub. For the complete set of methods, check GitHub.swift
- For utility methods to create a commit by updating a set of files, check GitHub+FileUpdating.swift
- For methods checking an existance of a specific branch, check GitHub+BranchChecking