Gateflow | GitHub CI/CD Integration

Automates PR labeling, release creation, CI workflows and more via GitHub webhooks.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

Gateflow is a GitHub App that listens to GitHub webhook events and automates your repository workflows. Connect it to your repos and let it handle the repetitive stuff — labeling PRs, triggering CI pipelines, creating releases, and more.

No more manually tagging PRs or forgetting to add labels. Gateflow reacts to events in real time and keeps your workflow consistent.

Built With

Getting Started

To get a local copy up and running, follow these steps.

Prerequisites

• Node.js 18+
• A GitHub App registered on your account or organization (create one here)
• A public URL or tunnel (e.g. ngrok) to receive webhook events locally

Installation

1. Clone the repo

git clone https://github.com/lukas-sgx/gateflow.git
cd gateflow

2. Install dependencies

npm install

3. Copy the example environment file and fill in your GitHub App credentials

cp .env.example .env

INSTALLATION_ID=YOUR_INSTALLATION_ID
APP_ID=YOUR_APP_ID
PRIVATE_KEY=YOUR_SECRET_KEY

4. Start the server

npm start prod

Usage

Once running, Gateflow listens for incoming GitHub webhook payloads. Here's an example of what happens when a PR is opened:

[webhook] pull_request.opened → #42 "feat: add dark mode"
  ├── title matches pattern "feat:*"   → label: enhancement
  ├── files changed: src/styles/**     → label: ui
  └── author: first-time contributor  → label: good first issue

Labeling rules are defined in a config file at the root of your repository:

# .gateflow.yml
labels:
  - pattern: "feat:*"
    label: enhancement
  - pattern: "fix:*"
    label: bug
  - paths:
      - "src/styles/**"
    label: ui

For more advanced examples, please refer to the Documentation.

Roadmap

• GitHub webhook receiver
• Automated PR labeling from title patterns
• Automated PR labeling from changed file paths
• Automated release creation on merge to main
• CI workflow triggers based on PR events

See the open issues for a full list of proposed features and known issues.

Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Top contributors:

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Lukas Soigneux - lukas.soigneux@epitech.eu

Acknowledgments

• Octokit - GitHub API client
• GitHub Webhooks Docs - Official webhook reference