Azure Bot

• Azure Bot
  • Prerequisites
    • Tools
  • Install
    • Clone the Repository
    • Create Web App in Azure
    • Deployment
    • Running Hubot locally
  • Next Steps
    • Adding persistent state to Hubot
      • Blob storage
      • Redis
    • Adding scripts to this bot
    • Scripts provided with this bot
  • Hubot / MS-Teams Bot integrations
    • Connect to VSTS
    • Connect to GitHub
    • Monitoring
    • Sparkles

Azure Bot is a chat bot built on the Hubot framework. It was initially generated by generator-hubot, and configured to be deployed on Azure

This README is intended to help get you started. Feel free to update and improve to talk about your own instance, how to use and deploy, what functionality is available, etc!

Prerequisites

• Create a Personal Access Token in GitHub that you will use to authenticate as you deploy Hubot
  • You may want to consider creating an automation account to own this personal access token
• If you are using SAML authentication for your GitHub organization, you may need to authorize this token

Tools

Tool	Used for
GitHub (Please log in now)	To store and version code
Slack team (Please create a new Slack team)	To interact with your chatbot
Azure (Please Authenticate)	To host your chatbot
Microsoft Teams (Please authenticate)	To interact with your chatbot

Install

To install and connect the Azure Hubot to your Azure environment you will need to complete the following actions:

Clone the Repository

Clone This repository to your GitHub Organization

• You will want to set this up as a private repository and give all members of your organization write access to allow inner-sourcing
• This will allow for greater contributions and speed up the development process

Create Web App in Azure

Connect to your Azure web portal and authenticate. You will then need to complete the following actions:

• Select Create a resource
• Select Web App
  • Fill in the form data
  • Select Create
• Go to your newly created application on the dashboard
• Configure environment variables that your Hubot will need to use
  • Select application settings
  • Navigate to General Settings
    • Select Always On
  • Navigate to the Application Settings section
  • Select Add new setting to create key pairs:
    • HUBOT_SLACK_TOKEN=Your Created Slack Token
    • HUBOT_ADAPTER=slack
    • BOT_NAME=YourHubotName
    • BOT_EMAIL=[email protected]
    • HUBOT_LOG_LEVEL=debug (optional)
    • GITHUB_API_TOKEN=YourPATFromGitHub
    • SCM_REPOSITORY_PATH=wwwroot
    • IN_PLACE_DEPLOYMENT=1
  • Select Save from top banner
    • NOTE: If you are using a different chat tool, you will need to configure different environment variables
• Set up automatic deployment of this app from your GitHub repository
  • Select Deployment options
  • Select Choose source
  • Select GitHub
    • Fill in the form data
    • NOTE: Use GitHub API Token that has write access to this repository
    • Select the correct Azure Hubot repository

Deployment

The first time you deploy this you may need to select the sync button of Deployment Options to start the application the first time.
Any time the master branch of your Azure Hubot repository is updated, it will trigger the Azure Deployment and update the Hubot. The Hubot only takes around 30-90 seconds to be re-deployed. NOTE: The first deployment will take longer as it will need to pull in many of the base dependencies.

Running Hubot locally

When developing additional features for Hubot, you will want to be able to develop and test locally. This can be achieved by cloning this repository to your local machine and running bin/hubot. The default adapter for this locally run instance is a shell console which provides a simple read-eval-print loop with which to interact. If you have a different adapter with access to your locally-hosted hubot, you can set the adapter option. For example, with slack the command would be bin/hubot -a "slack".

---

Next Steps

Adding persistent state to Hubot

Hubot is built with an in-memory key-value store called robot.brain. Some high-level documentation can be found here. In order to ensure that everything you save to robot.brain will persist as you update or temporarily stop your bot, you will want to sync it with an external datastore. There are presently two options available to persist data using azure: blob storage and Redis.

Blob storage

This repository contains the script, scripts/azure-brain.coffee, which provides a solution to integrate with an Azure blob storage service. To enable this, complete the following actions:

• Select Create a resource
• Select Storage -> Storage account
• Fill in the form data
  • Select Blob storage under Account kind
• Select Create
• Navigate to the Access keys section and copy the key1 -> Connection string
• Return to your Hubot web app and navigate to Application settings
  • Add the copied Access key as a new environment variable with key: HUBOT_BRAIN_AZURE_CONNSTRING

Redis

If you would prefer to use a redis cache for persistence, take the following steps:

• Note: The hubot-redis-brain plugin which is used to connect to redis caches currently does not support SSL encryption. If encryption is required by your internal policies, use the blob storage option instead.
• Select Create a resource
• Select Databases -> Redis Cache
• Fill in the form data
  • Check the box, Unblock port 6379 (not SSL encrypted)
• Select Create
• Navigate to the Access keys
  • Check the Primary key for special characters. NodeJS's redis library is sensitive to \ and :, so if the key contains these select Regenerate Primary until the key does not contain these characters
• Copy the Primary connection string
• Paste the string into a text editor
• Reformat the string to take the following form, ensuring that you replace the port 6380 with 6379: redis://:<PASSWORD>@<CONNECTION_DOMAIN>:6379
  • Example: if given the connection string, migarjoredis.redis.cache.windows.net:6380,password=123456=,ssl=True,abortConnect=False, your new string should take the form: redis://:[email protected]:6379
• Return to your Hubot web app and navigate to Application settings
  • Add your reformatted connection string as a new environment variable with key: REDIS_URL
• In your Hubot repository, add hubot-redis-brain to external-scripts.json and redeploy to Azure

Adding scripts to this bot

Hubot is a node app running coffeescript modules that can be written within the scripts folder. One common pattern is to use a coffeescript wrapper that calls scripts in other languages so you can write Hubot in any scripting language you're comfortable with.

Scripts provided with this bot

This instance of hubot includes a few modules and custom scripts, both as npm modules found in external-scripts.json and custom scripts found in scripts/:

• scripts/create-repo: This module interprets the input given by the user and calls a bash script at scripts/shell/create-and-protect-repo.sh to create a github repository. These example files include documentation to implement this for other uses.

• remember: Remembers key-value pairs when given the command, hubot remember <key> is <value>. Afterward, the value can be recalled with hubot remember <key>.

• hubot-auth: Assigns roles to users and restricts command access in other scripts. Roles can be assigned by anyone whose user id approved in a comma-delimited list in the environment variable, HUBOT_AUTH_ADMIN.

• In order to use "remember" and "hubot-auth", it is strongly recommended to implement data persistence to ensure that your assigned roles are preserved as the hubot app is shut down for updates or maintenance.

---

Hubot / MS-Teams Bot integrations

Connect to VSTS

You will want to connect the bot from your Chat tooling into VSTS.
This integration should be able to complete at the minimum the following actions:

• Show queue
• Start build
• List Jobs

Other actions are greatly encouraged, and can be seen as enhancements.

Connect to GitHub

You will want to connect the bot from your Chat tooling into GitHub.
This integration should be able to complete at the minimum the following actions:

• List Repositories
• Create Repository
• List members of team

Other actions are greatly encouraged, and can be seen as enhancements.

Monitoring

Having your bot be able to connect to your monitoring environment is a great step in maturity.
The ability to query information or metrics gives you a quick insight to your environment from your chat environment.
This allows teams to collaborate in real time about the environment and have a record of what is happening. Commands that allow you to fetch metrics and graphs, as well as check endpoints can greatly increase your culture and promote your environments.

Sparkles

Sparkles Giving your teammates points for doing something special is a great way to build culture and promote sharing.
This can be added and enhance your culture.