This repository hosts the source code of an automation app to handle the daily activities of your GitHub Repository.
The automation app utilizes the Probot framework and Octokit library to perform user-defined operations on top of the resources within GitHub. See configs yaml for more information.
A Service
is an instance of the app that manages and manipulates specific Resource
while performing defined Operation
.
- Resource: Objects or entities the service will manage or modify, such as GitHub organizations, project, repositories, issues, etc.
- Operation: A list of
Tasks
triggered by events with the resources. - Task: Executed sequentially within an
Operation
to perform action, such as create comments, update labels, add issue to project, etc. - Call: The callstack that contains the implementation of the aformentioned task action.
To create a service, you need two configuration files:
- Resource configuration file: Defines the resources that the service will manage or modify. Sample Resource Config.
- Operation configuration file: Defines the operations (tasks) that the service will execute with the resources. Sample Operation Config.
Before starting the service, create a .env
file to connect it to your GitHub App by copying the .env.example
file from this repository to .env
.
Once you have created the .env
file, resource / operation configuration files, follow these steps to start the service:
- Set the
RESOURCE_CONFIG
environment variable to the path of the resource configuration YAML file. - Set the
OPERATION_CONFIG
environment variable to the path of the operation configuration YAML file. - Update the
INSTALLATION_ID
variable in.env
file. (How to find installation id of your GitHub App) - Update your GitHub App settings on the GitHub website by defining the app's permissions and specifying the events to monitor.
- Run the service using the following command.
- (First Time Only) If you have created a new
.env
file, you will be directed tohttp://localhost:3000
as seen in the console message. Open this URL in your browser and follow the instructions to set up the necessary information.
RESOURCE_CONFIG=configs/resources/sample-resource.yml \
OPERATION_CONFIG=configs/operations/sample-operation.yml \
npm run dev
Note: You should run npm run start
instead in production to run prettier / eslint / jest before starting the service.
When you run the above command, the following takes place:
- The app starts a
Service
instance based on the specified configurations. - Retrieves the GitHub Context (or any other defined context) for all the resources listed in the resource config file.
- Registers and listens for events, executes the
Tasks
defined in the operation config. These tasks will be executed sequentially when the corresponding events occur.
List of Environment Variables (You can use them directly in the startup command, export them, or add them to the .env
file):
Name | Type | Default | Description | Example |
---|---|---|---|---|
RESOURCE_CONFIG | String | '' | Path to resource config yaml file. | 'configs/resources/sample-resource.yml' |
OPERATION_CONFIG | String | '' | Path to operation config yaml file. | 'configs/operations/sample-operation.yml' |
INSTALLATION_ID | String | '' | Installation Id of your GitHub App, must install the App to repositories before retrieving the id. | '1234567890' |
ADDITIONAL_RESOURCE_CONTEXT | Boolean | false | Setting true will let each resource defined in RESOURCE_CONFIG to call GitHub Rest API and GraphQL for more detailed context (ex: node_id). Increase startup time. | true / false |
SERVICE_NAME | String | 'default' | Set Service Name | 'My Service' |
For detailed instructions on starting the service with Docker, refer to the project's Docker Setup.
Please bump package version with every new commit by updating package.json
and run npm install
to update package-lock.json
. Please do not use npm version <>
as it will not sign DCO for your commit.
This project has adopted the Open Source Code of Conduct.
If you discover a potential security issue in this project we ask that you notify OpenSearch Security directly via email to security@opensearch.org. Please do not create a public GitHub issue.
This project is licensed under the Apache v2.0 License.
Copyright OpenSearch Contributors. See NOTICE for details.