Note: If you're confortable modifying package.json file manually, every time you need to register a package as a dependency, you can do it manually. It's not necessary to install it locally since this hubot instance is not going to be executed locally. The --save switch in the command guarantees that the package is registered as a dependency.

Visual Studio Online will send room messages to hubot using Basic Authentication. You'll need to define hubot
basic authentication credentials by setting the variables HUBOT_VSONLINE_ADAPTER_BASIC_AUTH_USERNAME and HUBOT_VSONLINE_ADAPTER_BASIC_AUTH_PASSWORD, these are the credentials that Visual Studio Online service consumers will use to authenticate when sending events to Hubot. It's highly recommended to use strong passwords.

Set Visual Studio Online account name: HUBOT_VSONLINE_ACCOUNT. The account name is the subdomain part you use when accessing to Visual Studio Online.
If you access with http://testaccount.visualstudio.com then the account name is testaccount.

% azure site appsetting add HUBOT_VSONLINE_ACCOUNT=<account name>

Set Visual Studio Online alternate credentials of the hubot user: HUBOT_VSONLINE_USERNAME and HUBOT_VSONLINE_PASSWORD

Set the rooms: HUBOT_VSONLINE_ROOMS. These are the rooms that you would like hubot to join (comma separated list with room names). This step is optional, hubot will respond to commands even if you don't specify rooms to join.

By default, Hubot uses Redis as its persistence storage. This hubot instance will use Azure Blob Storage
to persist its data. You'll use the hubot-azure-scripts module to persist data to a Azure Storage Account.
First, you'll need to register it as a dependency

% npm install hubot-azure-scripts --save

Then you need to edit the external-scripts.json to include the script that implements the brain

["hubot-azure-scripts/brain/storage-blob-brain"]

Then we need to remove the default Redis brain. Modify the file hubot-scripts.json and
remove the script redis-brain.coffee. After that the content of this file should be

["shipit.coffee"]

(to use an Azure storage you will need to use an existing one or create a new one on Azure portal)

Note It is advisable the storage account is on the same Azure region of the Azure website in order to reduce latency and not to iccur on data transfer costs. You should also add the storage as a linked resource to the web site.

You need to define the credentials to access storage by setting the variables

If you don't have an Azure Storage account, you can use the file system using the file-brain script that comes by default with hubot.
To use the file system as the persistence storage you'll need to change the file hubot-scripts.json and replace the string redis-brain.coffee
with file-brain.coffee. In the end you should see

["file-brain.coffee","shipit.coffee"]

Then you'll need to set the variable FILE_BRAIN_PATH which specifies the directory path where the hubot will store its data

Since the script is requiring coffee-script you'll need to register it as a dependency

% npm install coffee-script --save

Deploy to Azure using git

Add the current directory to git and commit

$ git add .
% git commit -m "Initial commit"

Push to azure

% git push azure master

You will be prompted for the password you created earlier when you defined deployment
credentials in the portal. Enter the password. You can find more information here
on how to publish from Git to Azure Web Sites.

Test your Hubot installation

At this point, you should be able to navigate on your browser to https://<name-of-your-site>.azurewebsites.net/hubot/help
You should see the list of commands available in Hubot.

Create a Visual Studio Online service hook subscription

For each Team Room you want to use Hubot, you'll need to create a
Hubot Service Hook subscription on a team project.
After selecting the room for this subscription use the following parameters:

At this point, any given user who is in a team room registered earlier in the variable HUBOT_VSONLINE_ROOMS is able to interact with hubot. You could check by entering in one of those rooms and send the message hubot ping

hubot ping
PONG

Visual Studio Online Scripts

One of the great things about hubot is that it's extensible, customizable and it allows you to add
your own scripts to perform the tasks you want. There is an open source project that provides some hubot
scripts targeting Visual Studio Online such as creating a bug, firing a build, etc. You can know more about this
project here.

At this point you should be able to issue commands to Visual Studio Online, where each
command will be performed using the hubot user that is running this instance. To check
what VSO commands are available:

hubot help vso
Hubot vso build <build number> - Triggers a build of the build number specified.
Hubot vso create pbi|bug|feature|impediment|task <title> with description <description> - Create a Product Backlog work item with the title and descriptions specified. This will put it in the root areapath and iteration
Hubot vso forget my credential - Forgets the OAuth access token
Hubot vso room default <key> = <value> - Sets room setting <key> with value <value>
Hubot vso builds - Will return a list of build definitions, along with their build number.
Hubot vso projects - Show the list of team projects
Hubot vso room defaults - Displays room settings
Hubot vso today - This will show a list of all tasks that you have updated today
Hubot vso me - Show user info as seen in Visual Studio Online user profile

To run commands on behalf of team room members continue reading.

Running Visual Studio Online commands impersonating users

To run Visual Studio Online scripts on behalf of the user who is sending the command,
the scripts support the OAuth 2.0 protocol to get an access token for a user and use it when
calling the Visual Studio Online REST APIs. You can get more information here.

It is advisable you enable this mode, otherwise Hubot Visual Studio Online scripts will run in trusted mode, this means all operations will be executed by Hubot account on behalf of the user. This the user will be able to perform all operations Hubot account as permissions too (and operations will be registered under Hubout account instead of the user account).

Follow the steps below to enable OAuth in scripts

Register an app in Visual Studio Online

Go to the profile page for your Visual Studio Online and register your app.
Fill all the required fields and make sure to fill the field Authorization Callback URL with

https://<name-of-your-site>.azurewebsites.net/hubot/oauth2/callback

replacing <name-of-your-site by the name of the site you created

You need to configure the following Authorized scopes

Work items (read and write)

Build (read and execute)

Code (read)

After you have created the app, you will need to configure the script with the value shown for the application you have registered.

Replace <App ID> by your App ID, <App Secret> by your App Secret, and <name-of-your-site> by the name of the site.

Restart the azure web site to make the new settings effective

Testing OAuth

At this point you could test the scripts using OAuth by sending the following message in the room

hubot vso me

hubot will respond with

I don't know who you are in Visual Studio Online. Click the link to authenticate <link to authenticate>

Click the link to start the OAuth dance in a new browser window. Follow the steps to authorize hubot to perform
tasks on your behalf. After the authorization, hubot replies you to the room with the message

You're <your display name> and your email is <your email address>"

hubot will keep the access token and will manage the refresh of tokens when it's expired.
If you want hubot to forget your authorization you'll need to send the message

Hardening Hubot

Hubot comes with a lot of scripts out of the box. Most of the scripts can be executed by everyone who has access to a room. Some commands may disclose information while others may be disruptive to hubot execution.

It is advisable that you harden your hubot installation to remove scripts that may lead to unwanted consequences.

This is just an example of some scripts that may leak information or can be disrupt hubot usage.

* storage.coffee - Implements the show storage, which allow any user to inspect hubot's brain content. While some restrictions apply it is possible that this command will disclose unwanted information depending what commands store in the brain.
* ping.coffee - Implements a die command. If this command is issue, hubot finishes itself. While this is harmfull if hubot is being executed under IIS like on a Azure web site, it is not harmfull if being executed under it's own process.

In case you want to remove these scripts, just delete from scripts folder in your hubot installation.

Troubleshooting

In case hubot is not responding to commands you will need to troubleshoot the issue.

First start by issuing some simple commands like "hubot ping" or "hubot help" to make sure you are not using a wrong command.

View the history of the event(s) that you have configured previously and check if the events are being delivered to hubot. If they are failing, you can see on the error message (summary tab) the reason on the failure. Perhaps you have entered the wrong URL or you are getting an "Unauthorized (401)" in that case you have configured the wrong credentials on the servie hook.

Let's separate this into two types of commands. Commands that do not require any interaction with Visual Studio Online from the ones who do (eg: show builds).

In order to better understand the issue we need to check why it's not responding to commands. Let's start by enabling the application log at the site level. Instructions here

Run the command

% azure site log tail

Replace <name-of-your-site>> by your web site name

You should see now see something similar to

info: Executing command site log tail
2014-XX-XXTXX:XX:XX Welcome, you are now connected to log-streaming service.

to see the Azure web site logs in real time

Non Visual Studio Online commands

If messages are reaching Hubot,

If responses from commands are being seen on the team room, it tipically due to two reasons:

The alternate credentials are not correct. In that case you will see in the logs something like

[TIME OMMITED (Coordinated Universal Time)] ERROR Failed to get hubot TF Id. will
not be able to respond to commands. Potential command ignored

Another cause for getting responses back, is due the lack of Chat permissions for the Hubot user in the chat room. In that case you will see the error:

Visual Studio Online related commands

If you are running Hubot in trusted mode, in which users are not impersonated if the Hubot user alternate credentials are wrong you will get the error

[TIME OMMITED (Coordinated Universal Time)] ERROR Failed to get hubot TF Id. will
not be able to respond to commands. Potential command ignored

If you are running Visual Studio Online commands in impersonating mode, in order run Visual Studio Online commands, you must first execute hubot vso me command and click on the link in order to authorize impersonation.

The following errors can occur:

1.If you have configured the wrong application identifier or the wrong callback, when you click on the link, a new window will appear on a Visual Studio Online with a big 400 and the message "BAD REQUEST We didn't understand the syntax of the request". Check both the the application identifier and the callback registed for your application and ensure they are correct on Hubot settings and restart Hubot

2.If you are using the wrong secret, clicking on the link will get you to an authorize page on Visual Studio Online. After authorization you will be redirected to an Hubot page where you will be greeted with the error on the browser