https://github.com/opensearch-project/automation-app
🤖 An automation app to handle the daily activities of your GitHub Repository.
https://github.com/opensearch-project/automation-app
Last synced: 2 months ago
JSON representation
🤖 An automation app to handle the daily activities of your GitHub Repository.
- Host: GitHub
- URL: https://github.com/opensearch-project/automation-app
- Owner: opensearch-project
- License: apache-2.0
- Created: 2024-09-18T21:33:11.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-03-12T21:54:35.000Z (4 months ago)
- Last Synced: 2025-04-04T16:42:02.672Z (3 months ago)
- Language: TypeScript
- Homepage:
- Size: 500 KB
- Stars: 5
- Watchers: 5
- Forks: 6
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
[](https://app.codecov.io/gh/opensearch-project/automation-app)
- [Welcome!](#welcome)
- [Project Resources](#project-resources)
- [Code of Conduct](#code-of-conduct)
- [Security](#security)
- [License](#license)
- [Copyright](#copyright)
## Welcome!
This repository hosts the source code of an automation app to handle the daily activities of your GitHub Repository.
## Project Resources
The automation app utilizes the [Probot](https://probot.github.io/) framework and [Octokit](https://docs.github.com/en/rest/using-the-rest-api/libraries-for-the-rest-api?apiVersion=2022-11-28) library to perform user-defined operations on top of the resources within GitHub. See [configs](configs) yaml for more information.
## Usages
### Service
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.
### Create a Service
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](configs/resources/sample-resource.yml).
- **Operation configuration file**: Defines the operations (tasks) that the service will execute with the resources. [Sample Operation Config](configs/operations/sample-operation.yml).
### Start the Service
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:
1. Set the `RESOURCE_CONFIG` environment variable to the path of the resource configuration YAML file.
1. Set the `OPERATION_CONFIG` environment variable to the path of the operation configuration YAML file.
1. Update the `INSTALLATION_ID` variable in `.env` file. ([How to find installation id of your GitHub App](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation#using-octokitjs-to-authenticate-with-an-installation-id))
1. Update your GitHub App settings on the GitHub website by defining the app's permissions and specifying the events to monitor.
1. Run the service using the following command.
1. (First Time Only) If you have created a new `.env` file, you will be directed to `http://localhost:3000` as seen in the console message. Open this URL in your browser and follow the instructions to set up the necessary information.
```bash
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:
1. The app starts a `Service` instance based on the specified configurations.
1. Retrieves the [GitHub Context](https://probot.github.io/api/latest/classes/context.Context.html) (or any other defined context) for all the resources listed in the resource config file.
1. 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' |
#### Start the Service with Docker
For detailed instructions on starting the service with Docker, refer to the project's [Docker Setup](./docker/README.md).
### Bump Package Version
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.
You can run `npm run build` before sending any Pull Request to ensure all the lint / format / test pass beforehand.
## Code of Conduct
This project has adopted [the Open Source Code of Conduct](CODE_OF_CONDUCT.md).
## Security
If you discover a potential security issue in this project we ask that you notify OpenSearch Security directly via email to [email protected]. Please do **not** create a public GitHub issue.
## License
This project is licensed under the [Apache v2.0 License](LICENSE).
## Copyright
Copyright OpenSearch Contributors. See [NOTICE](NOTICE) for details.