If you have read Brian Harry post Visual Studio Online Update – Sept 4th you may have noticed that with last week’s update (sprint 70) it is now possible to integrate Visual Studio Online with Hubot.
Although that is not 100% correct, it was already possible before, the fact is currently there is not too much information how to do it.
it is my intention with this post (the first from a series of three posts) to try to disseminate some information how to integrate Visual Studio Online with Hubot.
In this post I will try to show you, how can you perform Visual Studio Online tasks with an almost vanilla Hubot installation, on a second another post I will show you how to configure Hubot to use Visual Studio Online Team Rooms and finally on a third post, how you can run your Hubot installation from an Azure Web Site.
Hubot
Hubot has been developed by GitHub and it is a robot (or company’s robot has they put it) that allows automation of tasks from your chat room.
Hubot is extensible. It contains two extensibility points
- Scripts – Scripts are responsible to implement integration with other systems, to automate tasks. A script is a group of commands that implement that automation. You can add more scripts to automate tasks from other systems. There is a bunch of scripts kept by GitHub, but you can found a lot of scripts on the internet.
- Adapters – Out of the box, Hubot only supports Campfire as a chat room. But you can make it work it other systems, by installing another adapter. An adapter is responsible to implement the communication between Hubot and your chat room (in fact it doesn’t need to be a task room it can be IM systems like GTalk or any IM client which implements XMPP). GitHub maintains the “full” list of third party adapters and I’m sure others that are not on this list can be found on the internet.
Adapters and scripts are decoupled. The scripts just integrate with the external system, you can use any adapter you want and the scripts will just work.
Flunky would be a much better name for Hubot. He is allways ready to take orders from people issuing commands in chat rooms. Out of the box Hubot can do important stuff like show you Pug pictures, mustachify images, translate phrases and a lot of other stuff, but you can install a bunch of optional scripts to do even more stuff.
Visual Studio Online Hubot Script running modes
By now, you must have guessed that in order to integrate Hubot with Visual Studio Online we are going to use a script.
The script can be executed in two different modes.
- Trusted Mode – In trusted mode, all commands executed on Visual Studio Online (on behalf of the users) will be done with the Hubot user credentials. This mode is simpler to configure, but it has three disadvantages.
- This account needs permission (on the team projects) to perform all the operations you wish your users to issue. This may be extra work to administer or requires you to give permissions to access all team projects (an Über user so to speak)
- All operations will be performed with this account, thus you will lose auditability and the capability to understand who performed the operations (like work item changes and triggering builds)
- The user may be able to perform operations for which he doesn’t has permissions (as long as the hubot user can perform the requested operation)
- Impersonation Mode – On this mode all commands will be executed as if the user has executed it himself. But don’t worry Hubot doesn’t know the user credentials and before any command is executed as the user, the user will have to authorize hubot to execute comannds on behalf of the user (the user will only need to authorize this once and can ask Hubot to forget about him anytime). As you probably guessed by now, impersonation mode uses OAuth. Although this mode takes a little longer to configure (10 more minutes
) it has advantages.
- Since the operations will be executed as the user who issued the command, it means permissions will be checked by Visual Studio Online, therefore the user will be allowed to performed operations for which he has permissions
- The operations will be logged with the name of the user who issues the command, so operations will be auditable and more traceable (eg: if you see work item changes, they appear as performed by the user who issued the command).
Keep in mind that in order to use impersonation mode you will need to configure SSL on Hubot, this requires you to have certificate (there are some exceptions though)
I would recommend that you use Impersonation mode
Setting up Hubot Credentials
If you intend to use impersonation mode, then you can skip this step.
You need create an user in order to execute commands on Visual Studio Online. I’m going to omit detailed steps to create an account, but in simple terms you need to
- Create a Microsoft Account
- Login to Visual Studio Online and enabled alternate credentials
- Assign a license to the user
- Give permission to all team projects you want your users to issue commands against
Noticed that if you resort to the newly free stakeholder license the commands your users will be able to perform will be limited. (another reason to use OAuth no extra licenses needed)
Setting up OAuth
If you intend to use trusted mode, then you should skip this section.
Impersonation mode, requires the use of OAuth, to use OAuth on Visual Studio Online, you need to register an application in Visual Studio Online
In order to register an application go your Visual Studio Online profile page (you need to be logged) and click the Create a new Application link
Fill in at least the mandatory fields.
The Authorization callback should point to the URL:
https://<your hubot host name>/hubot/oauth2/callback
After you have saved your application, you will have a screen similar to this one
Later on you will need some of the values (App Id and App Secret) provided on this screen.
Install Visual Studio Integration on Hubot
I’m not going describe the details, how to install Hubot, that is well explained on Hubot deployment documentation
The simplest way to run, Hubot is to install it on Un*x machine, it took me less than 10 minutes to configure Hubot on a Ubuntu Linux instance running as an Azure Virtual machine.
To make things simpler, I have configured it to run on Campfire (since it’s supported by default), but you could configure an adapter to work with other popular group chat systems like Flowdock or HipChat (I will explain how to integrate with Visual Studio Team Rooms on another post).
BTW did you know Visual Studio integrates nicely with Campfire, Flowdock and HipChat. You can easily configure Visual Studio Online to send events (about builds, work item changes, source control….) to your chat rooms. You can read more about it on Integrate with other services
In order to add support for Visual Studio Online, you have to install hubot vso scripts you can do it by issuing the command
npm install hubot-vso-scripts
on the hubot folder and add it to your external-scripts.json as documented in the scripting section of reference Getting Started With Hubot guide
This may sound complicates, but you only need to edit the external-scripts.json and make sure it contains the Visual Studio Online hubot scripts referenced.
The file contains one array with the module name(s) of the external scripts.
Since I only have one external script, I just add one element to the array with the name NPM hubot vso script module.
After installing the module, you have to ensure the following environment variables are set before starting hubot daemon. The way you do id, depends how you are configuring hubot to start automatically, so I will just mention the variable names and it’s value, it’s up to you as a sysadmin to set them in the right place
General Parameters
- HUBOT_VSONLINE_ACCOUNT – The name of your account. (don’t include visualstudio.com it’s only the account name)
Parameters for trusted mode
If you see these parameters, the script will run in trusted mode.
- HUBOT_VSONLINE_USERNAME – the username of the account you created earlier in section Setting Hubot Credentials (either the primary or the secondary username)
- HUBOT_VSONLINE_PASSWORD – The password you have set up for the alternate credential
Parameters for Impersonation mode
- HUBOT_VSONLINE_APP_ID – The application Id. You can get this value from the application you have registered in Visual Studio Online
- HUBOT_VSONLINE_APP_SECRET – The application secret. You can get this value from the application you have registered in Visual Studio Online
- HUBOT_VSONLINE_AUTHORIZATION_CALLBACK_URL – The url you configured in section Setting up OAuth (it should be something like https://<your host name>/hubot/oauth2/callback)
Parameters to configure SSL
Note: If you have installed Hubot in which node is NOT setting up it’s own listener and the host provides you a reverse proxy (with HTTPS capabilities), this step is not necessary. For example this happens when node is hosted inside IIS (using IISNode) or a PaaS provider like Heroku or AppHarbor, in that case you can skip this step.
Remember you will need to configure SSL if you are using impersonation mode.
Those are the minimum set of parameters you need to enable SSL
- HUBOT_VSONLINE_SSL_ENABLE – Set this variable to true to enable SSL
- HUBOT_VSONLINE_SSL_PRIVATE_KEY_PATH – The file path to your SSL private key
- HUBOT_VSONLINE_SSL_CERT_KEY_PATH – The file path to your certificate
These parameters are optional
- HUBOT_VSONLINE_SSL_PORT – SSL port. By default it’s set to 443
- HUBOT_VSONLINE_SSL_CA_KEY_PATH – The path the certificate authority certificate (default is null)
- HUBOT_VSONLINE_SSL_REQUESTCERT – If we should request a client certificate (default is false)
- HUBOT_VSONLINE_SSL_REJECTUNAUTHORIZED - Check certificate against CA list. (Defaults to false)
If you haven’t done it yet, now you should configure campfire adapter.
You are now ready to launch your hubot daemon
Using Hubot
[note: I have configured Hubot with impersonation mode]
We are now ready to enter a campfire chat room, and start issuing commands to hubot.
On the right top corner you can see the persons who are in the chat room
You can notice, in this room called “hubot” (how original), right under the “Who’s here?” there are two persons. Me and Hubot.
Hubot is here listening to our commands, we can now start giving him orders. All commands start with the hubot keyword (unless you have configured a different one)
We can can start by issuing the hubot help command, to get a list of all available commands, or hubot vso help to get the list of the commands that really interest us. (all Visual Studio Online commands start with hubot vso)
This is the list of currently available commands on Visual Studio Online
Hubot vso assign <work item list> to @me | <user name> – Assigns one more or more work item(s) to you (@me) or a user name specified
Hubot vso build <build definition number> – Triggers a build
Hubot vso builds – Shows a list of build definitions
Hubot vso checkins [last <number> days] – Shows a list of TFVC checkins you have made in the last day (or specified number of days)
Hubot vso commits [last <number> days] – Shows a list of Git commits you have made in the last day (or specified number of days)
Hubot vso create pbi|requirement|bug|feature|impediment|task <title> with description <description> – Creates a work item, and optionally sets a description (repro step for some work item types)
Hubot vso forget credentials – Removes the access token issued to Hubot when you accepted the authorization request
Hubot vso help <search text> – Get help from VS related forums about the <search text>
Hubot vso me – Shows info about your Visual Studio Online profile
Hubot vso projects – Shows a list of projects
Hubot vso room default <key> = <value> – Sets a room default project, etc.
Hubot vso room defaults – Shows room defaults (e.g. project, etc)
Hubot vso status – Shows status for the Visual Studio Online service
Hubot vso today – Shows work items you have touched and code commits/checkins you have made today
Hubot vso update work remaining <work item id> to <hours remaining> – Updates work remaining on a work item
Our first command
I don’t intend to describe all commands. But let’s start with a simple one
I will issue the hubot vso me command. This will give me information about how hubot seems me in Visual Studio Online
Hubot says it doesn’t know me yet, and requires me to authorize him to do operations on my behalf,.
It’s nice enough to give me a link so I can authorize him. Clicking on the link will lead us to an authorization page (you don’t need to issue this command in particular, any command that requires interaction with Visual Studio Online will trigger (for the first time) the authorization request).
After clicking on accept
Your browser window will show you this message
and you will see a message on the chat room
with your name (your display name) and your email.
We are now ready to issue commands against Visual Studio Online.
If you wish to revoke your authorization, you can issue the command hubot vso forget me
Setting Room Defaults
Some commands operate over a team project or one or more Git repository. In order not to make users to keep writingt he same values over and over, you have to set default value for a room (these values will be automatically picked up by the commands)
You can set the room default values (you can change them anytime) with the command
Hubot vso room default <key> = <value>
Where key is the key name for which you want to see the <value>
Possible values for key
- project – The name of the default team project (for example for work item creation)
- repositories – the list of Git repositories (separated by commas).
This value is set per room, so each team can have it’s own room and have it’s own defaults
So let’s set a team project for later
You can get the default values for a given room with the command
Hubot vso room defaults
Creating a Work Item
Let’s now create a requirement in our default team project “tst CMMI”
hubot vso create requirement I can create work items from hubot with description It works
noticed hubot created a work item, replied with the work item id and a link to the work item.
Getting the list of changes I performed today
the vso today command, is great for stand ups. It shows the work items I’ve (as the user who issued the command) changed today and also my commits (if the team project is using Git) or checkins if using TFVC
Notice the work item it has been created on the previous command is listed
Assigning work items
You can also assign one or more work items (to assign more than one work item separate the ids with a comma) to your self or to another user
Hubot vso assign <work item list> to @me | <user name>
Note: The user name is the user display name
Update remaining work
Another command that is useful for daily stands ups is the
Hubot vso update work remaining <work item id> to <hours remaining>
Getting help from Visual Studio related MSDN forums
Another cool command, is the Hubot vso help <search text>
let’s try to get help about “how to list active bugs”
It shows the top 5 hits from MSDN forums and if you want the full list of results there is also a link to it.
Unfortunately campfire, doesn’t automatically make links clickable when the response contains more than one line (team rooms don’t have this issue )
Close up
I have not described all the available commands (remember you can issue at any time hubot help vso to get the full list of Visual Studio Online commands). I hope I have successfully shown you, how to configure Hubot to issue commands against Visual Studio Online and some of its potential.
On my next post, I will explain how you can configure Hubot to use Visual Studio Team rooms instead of Campire and on the third post of this series will show you, how you can configure Hubot to run on an Azure Web Site.
