← Home

GitHub Service

This page describes how to use the GitHub Service in the application.
It explains where to find the required information for proper setup and how to create trigger elements linked to this service.

---

Setup

First, you need to create two GitHub OAuth applications via this link, with these parameters:

• Authorization callback URL
  • For mobile: fr.lypitech.area://oauth-callback/github
  • For web: http://localhost:8081/callback
• Homepage URL: The link to your application's homepage. You can set https://github.com/lypitech/area.

[!CAUTION] For the web redirection URL, make sure you match the port the web listens to, otherwise the redirection will fail.

• Enable Device Flow: OFF

You now have the Client ID and Secret you can use in the environment variables.

---

Overview

The GitHub Service allows connecting a GitHub repository to the platform in order to trigger automations (Areas) when certain events occur, such as:

• a push to a branch
• a Pull Request being created or updated
• an Issue being opened, closed, or modified

The backend automatically creates and manages GitHub webhooks that send these events to the platform.

---

GitHub Trigger Structure

Example

{
  "service_name": "github",
  "name": "github_pull_request",
  "description": "Trigger on a pull_request event",
  "trigger_type": "webhook",
  "input": {
    "owner": "Timeotr",
    "repo": "testarea",
    "event": "pull_request"
  }
}

Input Fields

Field	Type	Required	Description
owner	string	✅	The repository owner (GitHub user or organization).
repo	string	✅	The GitHub repository name.
event	string	❌ (default: "push")	The type of GitHub event to listen for. Allowed values: "push", "pull_request", "issues".

[!IMPORTANT] If event is not provided or invalid, it will automatically default to "push".

---

Supported Events

Event	Description
push	Triggered when a push occurs on the repository.
pull_request	Triggered when a Pull Request is created, updated, or closed.
issues	Triggered when an Issue is created, edited, or closed.

---

Authentication

The GitHub Service uses an access token to communicate with the GitHub API.
Two authentication methods are supported:

1. Personal Access Token (PAT)

Defined via environment variables:

GITHUB_PAT
GITHUB_PERSONAL_ACCESS_TOKEN
GITHUB_TOKEN
GH_TOKEN

2. OAuth GitHub Token

Stored in the database for the connected user.

[!WARNING]
If no token is available, webhook creation will fail with a 401 Unauthorized error.

---

Webhook Creation

When a GitHub trigger is created, the backend performs the following steps:

1. Retrieves the user’s GitHub token.

2. Sends a request to the GitHub API:

   POST https://api.github.com/repos/{owner}/{repo}/hooks
   

3. Creates a webhook pointing to the platform callback URL:

   {BASE_URL}/hooks/github/{trigger_uuid}?token={webhook_secret}
   

4. Stores metadata in the database:

   • hookId
   • owner
   • repo
   • webhookSecret
   • event

---

Webhook Deletion

When a GitHub trigger is deleted, the backend removes the associated webhook:

DELETE https://api.github.com/repos/{owner}/{repo}/hooks/{hookId}

If the repository or webhook no longer exists, the error is ignored silently to avoid breaking workflows.

---

Debug Mode

The debug mode enables detailed logs for requests, responses, and API errors.

Activated when:

• NODE_ENV ≠ "production",
• or GITHUB_DEBUG=true.

Tokens and secrets are automatically masked in logs to prevent sensitive data exposure.

---

Summary

Key Element	Description
Service key	github:webhook
Supported triggers	push, pull_request, issues
Authentication	Personal Access Token or OAuth
Required inputs	owner, repo, event
Webhook method	POST /repos/{owner}/{repo}/hooks
Webhook deletion	DELETE /repos/{owner}/{repo}/hooks/{hookId}
Output payload	Complete GitHub payload + trigger metadata
Debug variable	GITHUB_DEBUG=true

---