@ubiquibot/plugin-template
Prerequisites
- A good understanding of how the kernel works and how to interact with it.
- A basic understanding of the Ubiquibot configuration and how to define your plugin's settings.
Getting Started
- Create a new repository using this template.
- Clone the repository to your local machine.
- Install the dependencies preferably using
yarn or bun.
Creating a new plugin
- If your plugin is to be used as a slash command which should have faster response times as opposed to longer running GitHub action tasks, you should use the
worker type.
- Ensure you understand and have setup the kernel.
- Update compute.yml with your plugin's name and update the
id.
- Update context.ts with the events that your plugin will fire on.
- Update plugin-inputs.ts to match the
with: settings in your org or repo level configuration.
- Your plugin config should look similar to this:
- plugin: <plugin-org/owner>/<plugin-repo-name>:compute.yml@development
name: plugin-name
id: plugin-name-command
description: "Plugin description" # small description of what the plugin does
command: "<regex for command>" # if you are creating a plugin with a slash command
example: "<example usage>" # how to invoke the slash command
with: # these are the example settings, the kernel passes these to the plugin.
disabledCommands: []
timers:
reviewDelayTolerance: 86000
taskStaleTimeoutDuration: 2580000
miscellaneous:
maxConcurrentTasks: 3
labels:
time: []
priority: []
At this stage, your plugin will fire on your defined events with the required settings passed in from the kernel. You can now start writing your plugin's logic.
- Start building your plugin by adding your logic to the plugin.ts file.
Testing a plugin
Worker Plugins
yarn/bun worker - to run the worker locally.- To trigger the worker,
POST requests to http://localhost:4000/ with an event payload similar to:
await fetch("http://localhost:4000/", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
stateId: "",
eventName: "",
eventPayload: "",
settings: "",
ref: "",
authToken: "",
}),
});
A full example can be found here.
Action Plugins
- Ensure the kernel is running and listening for events.
- Fire an event in/to the repo where the kernel is installed. This can be done in a number of ways, the easiest being via the GitHub UI or using the GitHub API, such as posting a comment, opening an issue, etc in the org/repo where the kernel is installed.
- The kernel will process the event and dispatch it using the settings defined in your
.ubiquibot-config.yml.
- The
compute.yml workflow will run and execute your plugin's logic.
- You can view the logs in the Actions tab of your repo.
Nektos Act - a tool for running GitHub Actions locally.
More information
- Full Ubiquibot Configuration - helpful for defining your plugin's settings as they are strongly typed and will be validated by the kernel.
- Ubiquibot V1 - helpful for porting V1 functionality to V2, helper/utility functions, types, etc. Everything is based on the V1 codebase but with a more modular approach. When using V1 code, keep in mind that most all code will need refactored to work with the new V2 architecture.
Examples