hubot README

The project's README from github.com/hubotio/hubot. As one markdown file: README.md.

Pipeline Status

Build Status: MacOS Build Status: Ubuntu Build Status: Window

Hubot

Note: v10.0.4 accidentally contains the removal of CoffeeScript; v10.0.5 puts it back in Note: v11 removes CoffeeScript and converts this codebase to ESM

Hubot is a framework to build chat bots, modeled after GitHub's Campfire bot of the same name, hubot. He's pretty cool. He's extendable with scripts and can work on many different chat services.

This repository provides a library that's distributed by npm that you use for building your own bots. See the documentation for details on getting up and running with your very own robot friend.

In most cases, you'll probably never have to hack on this repo directly if you are building your own bot. But if you do, check out CONTRIBUTING.md

Create your own Hubot instance

This will create a directory called myhubot in the current working directory.

npx hubot --create myhubot --adapter @hubot-friends/hubot-slack
npx hubot --create myhubot --adapter @hubot-friends/hubot-discord
npx hubot --create myhubot --adapter @hubot-friends/hubot-ms-teams
npx hubot --create myhubot --adapter @hubot-friends/hubot-irc

Review scripts/example.mjs. Create more scripts in the scripts folder.

Command bus (robot.commands)

Hubot includes a deterministic command subsystem for slash-style commands. It is safe by default and does not interfere with legacy hear and respond listeners.

Basic Command Registration

export default (robot) => {
	robot.commands.register({
		id: 'tickets.create',
		description: 'Create a ticket',
		aliases: ['ticket new', 'new ticket'],
		args: {
			title: { type: 'string', required: true },
			priority: { type: 'enum', values: ['low', 'medium', 'high'], default: 'medium' }
		},
		sideEffects: ['creates external ticket'],
		handler: async (ctx) => {
			return `Created ticket: ${ctx.args.title}`
		}
	})
}

Invoke with addressing the bot:

Commands that declare side effects will require confirmation before execution.

The user is asked to confirm. They do so like so:

@hubot yes
@hubot no
@hubot cancel

Aliases are for discovery and search only. They do not execute commands or create proposals. They are intent utterances.

Built-in Help Command

Hubot automatically registers a help command that provides command discovery and documentation:

@hubot help                          # List all commands
@hubot help tickets                  # Filter commands by prefix
@hubot help search "create ticket"   # Search by keyword, alias, description, or example

Search for Commands

const results = robot.commands.search('ticket new')
// [{ id: 'tickets.create', score: 100, matchedOn: 'alias' }, ...]

Custom Type Resolvers

Extend validation with custom argument types:

export default (robot) => {
	// Register custom type resolver
	robot.commands.registerTypeResolver('project_id', async (value, schema, context) => {
		if (!value.startsWith('PRJ-')) {
			throw new Error('must start with PRJ-')
		}
		return value.toUpperCase()
	})

	// Use it in a command
	robot.commands.register({
		id: 'projects.deploy',
		description: 'Deploy a project',
		args: {
			projectId: { type: 'project_id', required: true }
		},
		handler: async (ctx) => {
			return `Deploying ${ctx.args.projectId}`
		}
	})
}

Configuration Options

When creating a CommandBus instance, you can configure:

Permissions

Control who can execute commands using room-based and role-based permissions.

Room-Based Permissions

Restrict command execution to specific chat rooms:

robot.commands.register({
	id: 'sensitive.action',
	description: 'Admin-only action',
	permissions: {
		rooms: ['#admin', '#ops']  // Only allowed in these rooms
	},
	handler: async (ctx) => {
		return 'Action executed!'
	}
})

Users in other rooms get: Permission denied: command not allowed in this room

Role-Based Permissions

Restrict command execution to users with specific roles:

robot.commands.register({
	id: 'deploy.production',
	description: 'Deploy to production',
	permissions: {
		roles: ['admin', 'devops']  // Only users with these roles
	},
	handler: async (ctx) => {
		return 'Deploying...'
	}
})

To enable role checking, provide a permissionProvider when creating CommandBus:

const commandBus = new CommandBus(robot, {
	permissionProvider: {
		hasRole: async (user, requiredRoles, context) => {
			// Custom logic to check if user has any of the required roles
			const userRoles = await fetchUserRoles(user.id)
			return requiredRoles.some(role => userRoles.includes(role))
		}
	}
})

Without a permission provider, role-based permissions are ignored (allow by default). Room-based permissions are always enforced.

License

See the LICENSE file for license rights and limitations (MIT).

Hubot History

Say hello to Hubot

Cartoon with Hubot

The Most Important Startup's Hardest Worker Isn't a Person

The Story of Hubot

Hubot by Hubotics

Automating Inefficiencies

Getting Started with Hubot

hubot (hubotio/hubot)

event
Searching Database…

16.8K ·GitHub
Hubot
What is this?Hubot is a framework for building chat bots, modeled after GitHub's own internal Campfire bot of the same name. It's distributed as an npm library that you use to build your own bot which can run on many different chat services.
Is this a ready-made bot or a framework I build on top of?It's a library/framework, not a finished bot. You scaffold your own Hubot instance from it and then extend it with your own scripts and chat adapters.
How do I create my own bot with this?Run the generator to scaffold a new instance (e.g. `bin/hubot --create myhubot`), which creates a 'myhubot' directory, then add your own scripts to the scripts folder based on the provided example.
What do I need installed before running a Hubot bot?You need Node.js 18 or newer and npm 9 or newer; the core library itself depends on packages like express, express-basic-auth and pino.
Is upgrading between versions safe, especially around CoffeeScript?Be careful with versions: v10.0.4 accidentally removed CoffeeScript support, v10.0.5 restored it, and v11 removes CoffeeScript entirely and converts the codebase to ESM, so old CoffeeScript scripts may break on upgrade.
What is the command bus (robot.commands) feature?It is a deterministic subsystem for slash-style commands, addressed like '@hubot tickets.create --title "VPN down"'. It runs safely alongside legacy hear/respond listeners and can require user confirmation for commands that have side effects.
Can I restrict who uses certain commands?Yes, the command bus supports room-based permissions (restricting commands to specific chat rooms) and role-based permissions via a custom permissionProvider; room-based checks are always enforced, role checks only if you supply a provider.
Why was Hubot created?It was built at GitHub as 'the most important startup's hardest worker' - an internal Campfire chat bot used to automate inefficiencies like deployments, and was later open-sourced as this framework.
Does it ship with a built-in help system?Yes, Hubot automatically registers a help command that provides discovery and documentation for all registered commands, including aliases used purely for search.
What are similar projects?ItChat, Baileys, whatsapp-web.js, botkit, openclaw, cc-connect, wechaty, botpress
Which topics is it in?event, hack, scripts, robot, bot, express, chat, chatbot, framework, npm, automation, server
Creator
hubotio
Size
4.5 MB
Stars
16.8K
Updated
CommitOct 14Releasev14.1.0Feb 24
Age
15y
Commits · 90 Days