diff --git a/en/docs/connectors/catalog/developer-tools/github/actions.md b/en/docs/connectors/catalog/developer-tools/github/actions.md index 4f2a827e902..25b19d08a2b 100644 --- a/en/docs/connectors/catalog/developer-tools/github/actions.md +++ b/en/docs/connectors/catalog/developer-tools/github/actions.md @@ -9,24 +9,33 @@ The `ballerinax/github` package exposes the following clients: | Client | Purpose | |--------|---------| -| [`Client`](#client) | Provides access to the GitHub REST API (241 resource functions) for managing repositories, issues, pull requests, organizations, users, and more. | +| [`Client`](#client) | Provides access to the GitHub REST API (903 resource functions) for managing repositories, issues, pull requests, organizations, users, and more. | --- ## Client -Provides access to the GitHub REST API (241 resource functions) for managing repositories, issues, pull requests, organizations, users, and more. +Provides access to the GitHub REST API (903 resource functions) for managing repositories, issues, pull requests, organizations, users, and more. ### Configuration | Field | Type | Default | Description | |-------|------|---------|-------------| -| `auth` | `http:BearerTokenConfig\|http:OAuth2RefreshTokenGrantConfig` | Required | Authentication configuration. Typically a Personal Access Token supplied as a bearer token (e.g., `{token: ""}`). | -| `httpVersion` | `http:HttpVersion` | `HTTP_2_0` | HTTP protocol version. | -| `timeout` | `decimal` | `60` | Request timeout in seconds. | +| `auth` | `http:BearerTokenConfig` | Required | Authentication configuration. Supply a Personal Access Token (PAT) as a bearer token: `{token: ""}`. | +| `httpVersion` | `http:HttpVersion` | `HTTP_2_0` | HTTP protocol version used by the client. | +| `http1Settings` | `http:ClientHttp1Settings` | `()` | HTTP/1.x protocol settings including keep-alive and chunking behavior. | +| `http2Settings` | `http:ClientHttp2Settings` | `()` | HTTP/2 protocol settings. | +| `timeout` | `decimal` | `60` | Request timeout in seconds before the connection is closed. | +| `forwarded` | `string` | `"disable"` | Controls whether to set `forwarded` or `x-forwarded` headers. | +| `poolConfig` | `http:PoolConfiguration` | `()` | Connection pool configuration for request pooling. | +| `cache` | `http:CacheConfig` | `()` | HTTP caching configuration. | +| `compression` | `http:Compression` | `COMPRESSION_AUTO` | Compression handling for `accept-encoding` headers. | +| `circuitBreaker` | `http:CircuitBreakerConfig` | `()` | Circuit breaker configuration for fault tolerance. | | `retryConfig` | `http:RetryConfig` | `()` | Retry configuration for failed requests. | +| `responseLimits` | `http:ResponseLimitConfigs` | `()` | Inbound response size limits. | | `secureSocket` | `http:ClientSecureSocket` | `()` | SSL/TLS configuration. | | `proxy` | `http:ProxyConfig` | `()` | Proxy server configuration. | +| `validation` | `boolean` | `true` | When enabled, validates response payloads against declared schemas using the `constraint` package. | ### Initializing the client diff --git a/en/docs/connectors/catalog/developer-tools/github/connector-overview.md b/en/docs/connectors/catalog/developer-tools/github/connector-overview.md index a15d7dc878e..ddab09d99fd 100644 --- a/en/docs/connectors/catalog/developer-tools/github/connector-overview.md +++ b/en/docs/connectors/catalog/developer-tools/github/connector-overview.md @@ -1,7 +1,12 @@ -# Github Connector Overview +--- +title: GitHub Connector Overview +description: Manage repositories, issues, pull requests, and more using the Ballerina ballerinax/github connector for GitHub's REST API. +keywords: [wso2 integrator, github connector, ballerinax github, rest api, repositories, issues, pull requests] +--- -GitHub is a widely used platform for version control and collaboration, allowing developers to work together on projects from anywhere. The Ballerina `ballerinax/github` connector (v5.1.0) provides programmatic access to GitHub through its REST API (version 2022-11-28), enabling you to automate tasks, manage repositories, issues, pull requests, and more directly from Ballerina integration flows. +# GitHub Connector Overview +GitHub is a widely used platform for version control and collaboration, allowing developers to work together on projects from anywhere. The Ballerina `ballerinax/github` connector (v5.1.0) provides programmatic access to GitHub through its REST API (version 2022-11-28), enabling you to automate tasks, manage repositories, issues, pull requests, and more directly from Ballerina integration flows. ## Key features @@ -12,20 +17,27 @@ GitHub is a widely used platform for version control and collaboration, allowing - Organization and team management — list orgs, teams, and members - Gist management — create, update, list, star, fork, and comment on gists - Security advisory access — query global and repository-specific security advisories +- GitHub Actions and workflow management — list and trigger workflow runs +- Dependabot, code scanning, and secret scanning alert access - Event-driven webhook handling for GitHub issues, pull requests, releases, pushes, and repository activity - Resource-based API design using Ballerina resource functions for intuitive path-based access to GitHub REST endpoints ## Actions -Actions are operations you invoke on GitHub from your integration — managing repositories, creating issues, handling pull requests, and more. The GitHub connector exposes 241 resource functions through a single client: - +Actions are operations you invoke on GitHub from your integration — managing repositories, creating issues, handling pull requests, and more. The GitHub connector exposes 903 resource functions through a single client: | Client | Actions | |--------|---------| -| `Client` | Repository CRUD, issues, pull requests, branches, releases, organizations, teams, users, gists, security advisories, notifications | +| `Client` | Repository and file management, issues, pull requests, branches, releases, organizations, teams, users, gists, security advisories, notifications, GitHub Actions and workflows, Dependabot alerts, code scanning, secret scanning, packages, deployments, and more | See the **[Action Reference](actions.md)** for the full list of operations, parameters, and sample code for each client. +## Event-driven integration + +To receive GitHub webhook events (issues, pull requests, releases, pushes, and more), use the separate [`ballerinax/trigger.github`](https://github.com/ballerina-platform/module-ballerinax-trigger.github) package. It provides a `Listener` and service types (`IssuesService`, `PullRequestService`, and others) that route incoming GitHub webhook callbacks to typed event handlers. + +See the [GitHub Webhooks](../../../develop/integration-artifacts/event/github-webhooks.md) guide for configuration and usage. + ## Triggers Triggers allow your integration to react to GitHub repository activity in real time. The connector provides a webhook listener that receives GitHub events and invokes your service callbacks automatically when issues, pull requests, releases, pushes, and other repository events occur. @@ -48,7 +60,6 @@ See the **[Trigger Reference](triggers.md)** for listener configuration, service * **[Setup Guide](setup-guide.md)**: This guide walks you through creating a GitHub Personal Access Token (PAT) required to authenticate with the GitHub connector. - * **[Action Reference](actions.md)**: Full reference for all clients — operations, parameters, return types, and sample code. * **[Trigger Reference](triggers.md)**: Reference for event-driven integration using the GitHub webhook listener and service model. @@ -61,6 +72,13 @@ As an open source project, WSO2 welcomes contributions from the community. To contribute to the code for this connector, please create a pull request in the following repository. -* [Github Connector GitHub repository](https://github.com/ballerina-platform/module-ballerinax-github) +* [GitHub Connector repository](https://github.com/ballerina-platform/module-ballerinax-github) Check the issue tracker for open issues that interest you. We look forward to receiving your contributions. + +## What's next + +- [Setup Guide](setup-guide.md) — create a GitHub Personal Access Token for authentication +- [Action Reference](actions.md) — full list of operations, parameters, and sample code +- [Example](example.md) — step-by-step integration walkthroughs +- [GitHub Webhooks](../../../develop/integration-artifacts/event/github-webhooks.md) — listen for GitHub events using webhooks diff --git a/en/docs/connectors/catalog/developer-tools/github/example.md b/en/docs/connectors/catalog/developer-tools/github/example.md index b1a63db1562..cf57d0985f0 100644 --- a/en/docs/connectors/catalog/developer-tools/github/example.md +++ b/en/docs/connectors/catalog/developer-tools/github/example.md @@ -1,10 +1,13 @@ -# Example - +--- +title: Examples +description: Step-by-step examples for using the GitHub connector to create issues and listen for GitHub webhook events in WSO2 Integrator. +keywords: [wso2 integrator, github connector example, github webhook trigger, create issue, event integration] +--- -## Table of Contents +import ThemedImage from '@theme/ThemedImage'; +import useBaseUrl from '@docusaurus/useBaseUrl'; -- [GitHub Example](#github-example) -- [GitHub Trigger Example](#github-trigger-example) +# Example ## GitHub Example @@ -38,27 +41,44 @@ flowchart LR Select **+ Add Artifact** on the Integration Design canvas. In the **Artifacts** panel, scroll to **Other Artifacts** and select **Connection**. The connector search palette appears with a search box and a grid of pre-built connectors. -![GitHub connector palette open with search field before any selection](/img/connectors/catalog/developer-tools/github/github_screenshot_01_palette.png) - + ### Configuring the GitHub connection -#### Step 2: Fill in the connection parameters +### Step 2: Fill in the connection parameters Enter `github` in the search box to filter results, then select the **GitHub** connector card. In the connection configuration form, bind the connection fields to configurable variables: - **auth.token** : Personal access token used to authenticate GitHub API requests - **Connection Name** : Logical name for this connection (`githubClient`) -![GitHub connection form fully filled with all parameters before saving](/img/connectors/catalog/developer-tools/github/github_screenshot_02_connection_form.png) + -#### Step 3: Save the connection +### Step 3: Save the connection Select **Save Connection**. The form closes and the canvas reloads, showing the `githubClient` node. -![GitHub Connections panel showing githubClient entry after saving](/img/connectors/catalog/developer-tools/github/github_screenshot_03_connections_list.png) + -#### Step 4: Set actual values for your configurables +### Step 4: Set actual values for your configurables 1. In the left panel, select **Configurations**. 2. Set a value for each configurable listed below. @@ -66,6 +86,7 @@ Select **Save Connection**. The form closes and the canvas reloads, showing the - **githubAuthToken** (string) : Your GitHub personal access token with `repo` scope ## Configuring the GitHub create an issue operation + ### Step 5: Add an automation entry point 1. Select **+ Add Artifact** on the Integration Design canvas. @@ -78,7 +99,13 @@ WSO2 Integrator creates a `main` automation under **Entry Points** and opens the On the Automation canvas, select the **+** between **Start** and **Error Handler** to open the node panel. Under the **Connections** section, expand `githubClient` to reveal all available operations. -![GitHub connection node expanded showing all available operations before selection](/img/connectors/catalog/developer-tools/github/github_screenshot_04_operations_panel.png) + ### Step 7: Configure the create an issue operation @@ -93,9 +120,21 @@ Select **Create an issue** from the operations list and fill in all required fie Select **Save** to apply the configuration. -![GitHub Create an issue operation configuration filled with all values](/img/connectors/catalog/developer-tools/github/github_screenshot_05_operation_values.png) - -![Completed GitHub automation flow](/img/connectors/catalog/developer-tools/github/github_screenshot_06_completed_flow.png) + + + ### Try it yourself @@ -117,13 +156,16 @@ The `GitHub` connector provides practical examples illustrating usage in various 4. [Star Ballerina-Platform Repositories](https://github.com/ballerina-platform/module-ballerinax-github/tree/master/examples/star-ballerina-repositories) - Fetch all repositories under the `ballerina-platform` organization on GitHub and star each of them - ---- ## GitHub Trigger Example + ### What you'll build This integration listens for GitHub issue events using the `ballerinax/trigger.github` package and the `IssuesService` event channel. When a GitHub user opens, closes, or modifies an issue, GitHub sends a webhook POST request to the listener, which routes the event to the appropriate handler. The `onOpened` handler receives the `github:IssuesEvent` payload and logs it as a JSON string using `log:printInfo`. +:::info +This example uses the `ballerinax/trigger.github` package, which is separate from the `ballerinax/github` REST API connector. Use `ballerinax/github` for calling GitHub APIs; use `ballerinax/trigger.github` for receiving GitHub webhook events. +::: + ### Architecture ```mermaid @@ -144,61 +186,92 @@ flowchart LR ### Adding the GitHub trigger -#### Step 1: Open the artifacts palette +### Step 1: Open the artifacts palette Select **Add Artifact** to open the artifacts palette. Select the **Event Integration** category and locate the **GitHub** trigger card. -![Artifacts palette open showing the Event Integration category with the GitHub trigger card highlighted, before clicking the card](/img/connectors/catalog/developer-tools/github/github_trigger_screenshots_01_artifact_palette.png) + ### Configuring the GitHub listener -#### Step 2: Bind listener parameters to configurable variables +### Step 2: Bind listener parameters to configurable variables Select the **GitHub** card to open the **Create GitHub Event Integration** form. The **Event Channel** dropdown is pre-set to `IssuesService`. Bind the two required fields to configurable variables: - **webhookSecret** : Secret token used to validate incoming GitHub webhook requests - **listenerPort** : Port on which the webhook listener accepts incoming HTTP requests from GitHub -![GitHub trigger configuration form fully filled with Event Channel set to IssuesService, Webhook Secret bound to webhookSecret configurable variable, and Webhook Listener Port bound to listenerPort configurable variable, with Create enabled](/img/connectors/catalog/developer-tools/github/github_trigger_screenshots_02_trigger_config_form.png) + -#### Step 3: Set actual values for your configurations +### Step 3: Set actual values for your configurations In the left panel, select **Configurations** to open the Configurations panel. Set a value for each configuration listed below: - **webhookSecret** (string) : Secret token matching the value configured in your GitHub repository's webhook settings - **listenerPort** (int) : Port number on which the webhook listener will accept incoming requests from GitHub -![Configurations panel open showing webhookSecret (string, Required) and listenerPort (int, Required) with empty value fields](/img/connectors/catalog/developer-tools/github/github_trigger_screenshots_03_configurations_panel.png) + -#### Step 4: Create the trigger +### Step 4: Create the trigger Select **Create** to submit the trigger configuration and generate the `IssuesService` listener. ### Handling GitHub events -#### Step 5: Review auto-registered event handlers +### Step 5: Review auto-registered event handlers -Navigate to the **github:IssuesService** service view. GitHub's `IssuesService` auto-registers all handlers when the event channel is selected—there's no separate **Add Handler** side panel for this trigger. The **Event Handlers** list includes: +Navigate to the **github:IssuesService** service view. GitHub's `IssuesService` auto-registers all handlers when the event channel is selected — there's no separate **Add Handler** side panel for this trigger. The **Event Handlers** list includes: - `onOpened` — triggered when an issue is opened - `onClosed` — triggered when an issue is closed - `onReopened` — triggered when an issue is reopened - `onAssigned`, `onUnassigned`, `onLabeled`, `onUnlabeled` -![GitHub IssuesService view showing all auto-registered event handlers (onOpened, onClosed, onReopened, onAssigned, onUnassigned, onLabeled, onUnlabeled) with the Listener and Event Channel badges visible (Auto-registered IssuesService handlers — no Add Handler side panel for this trigger)](/img/connectors/catalog/developer-tools/github/github_trigger_screenshots_04_add_handler_panel.png) + -#### Step 6: Inspect the onOpened handler flow +### Step 6: Inspect the onOpened handler flow Select the **onOpened** row to open its flow canvas. At this stage the handler body contains only the **Start** node and the **Error Handler** wrapper. -> **Note:** GitHub `IssuesService` handler parameter types (`github:IssuesEvent`) are fixed by the service interface—there's no Define Value / Create Type Schema modal for this trigger. The payload type is provided by the package. +:::info +The `github:IssuesEvent` payload type is fixed by the `IssuesService` interface — you cannot change it. The type is provided by the `ballerinax/trigger.github` package and does not have a Define Value or Create Type Schema modal. +::: - -#### Step 7: Add the log statement +### Step 7: Add the log statement Select the **+** icon in the flow chart, and in the side panel that opens, choose **Log Info** from the **Logging** section, then enter `payload.toJsonString()` as the message. -![onOpened handler flow canvas showing the inserted log:printInfo node (payload.toJsonString()) between Start and Error Handler after the pro-code edit](/img/connectors/catalog/developer-tools/github/github_trigger_screenshots_06_handler_flow.png) + ### Running the integration @@ -221,3 +294,10 @@ Try this sample in WSO2 Integration Platform. [![Deploy to Devant](https://openindevant.choreoapps.dev/images/DeployDevant-White.svg)](https://console.devant.dev/new?gh=wso2/integration-samples/tree/main/integrator-default-profile/connectors/github_trigger_sample) [View source on GitHub](https://github.com/wso2/integration-samples/tree/main/integrator-default-profile/connectors/github_trigger_sample) + +## What's next + +- [GitHub Webhooks](../../../../develop/integration-artifacts/event/github-webhooks.md) — full reference for all event channels and handlers +- [Setup Guide](setup-guide.md) — create a GitHub Personal Access Token and configure a repository webhook +- [Action Reference](actions.md) — full list of REST API operations and sample code + diff --git a/en/docs/connectors/catalog/developer-tools/github/setup-guide.md b/en/docs/connectors/catalog/developer-tools/github/setup-guide.md index 5118f3a3b39..9bdc2457799 100644 --- a/en/docs/connectors/catalog/developer-tools/github/setup-guide.md +++ b/en/docs/connectors/catalog/developer-tools/github/setup-guide.md @@ -1,9 +1,11 @@ --- title: Setup Guide +description: Create a GitHub Personal Access Token (PAT) and configure a GitHub repository webhook for use with the GitHub connector and GitHub Events integration. +keywords: [wso2 integrator, github setup, personal access token, PAT, github webhook, webhook secret] --- # Setup Guide -This guide walks you through creating a GitHub Personal Access Token (PAT) required to authenticate with the GitHub connector. +This guide walks you through creating a GitHub Personal Access Token (PAT) required to authenticate with the GitHub connector, and configuring a GitHub repository webhook for event-driven integrations. ## Prerequisites @@ -27,7 +29,7 @@ This guide walks you through creating a GitHub Personal Access Token (PAT) requi 2. Select **Tokens (classic)** or **Fine-grained tokens** depending on your preference. :::tip -Fine-grained tokens offer more granular permissions and are recommended for production use. Classic tokens provide broader scope-based access. +Fine-grained tokens offer more granular permissions and are recommended for production use. Classic tokens provide broader scope-based access. Both token types work identically with the GitHub connector — the choice affects only the permission scope, not connector configuration. ::: ## Step 4: Generate a new token @@ -49,3 +51,54 @@ Fine-grained tokens offer more granular permissions and are recommended for prod :::warning Store the token securely. Do not commit it to source control. Use Ballerina's `configurable` feature and a `Config.toml` file to supply it at runtime. ::: + +## Configuring a GitHub repository webhook + +If you are using the [GitHub Webhooks](../../../develop/integration-artifacts/event/github-webhooks.md) event integration, you must configure a webhook in your GitHub repository to send events to your listener endpoint. + +### Prerequisites + +- Admin access to the GitHub repository +- Your WSO2 Integrator listener URL (for example, `https://your-host:8090`) +- A webhook secret value — a random string you choose that must match the `webhookSecret` value in your integration + +### Step 1: Open webhook settings + +1. Go to your GitHub repository. +2. Click **Settings** → **Webhooks** → **Add webhook**. + +### Step 2: Configure the webhook + +Fill in the following fields: + +| Field | Value | +|---|---| +| **Payload URL** | Your listener endpoint URL (for example, `https://your-host:8090`) | +| **Content type** | `application/json` | +| **Secret** | The same value you set as `webhookSecret` in your integration | +| **SSL verification** | Enable if your listener uses HTTPS | + +### Step 3: Select events + +Choose **Let me select individual events** and enable only the events that match your service type: + +| If you use | Enable GitHub event | +|---|---| +| `IssuesService` | **Issues** | +| `IssueCommentService` | **Issue comments** | +| `PullRequestService` | **Pull requests** | +| `PullRequestReviewService` | **Pull request reviews** | +| `PullRequestReviewCommentService` | **Pull request review comments** | +| `ReleaseService` | **Releases** | +| `LabelService` | **Labels** | +| `MilestoneService` | **Milestones** | +| `PushService` | **Pushes** | +| `ProjectCardService` | **Project cards** | + +### Step 4: Save + +Click **Add webhook**. GitHub will send a ping event to your endpoint to verify connectivity. + +:::warning +Always set a webhook secret. Without it, your listener accepts requests from any source — not just GitHub. The secret is used to verify the `X-Hub-Signature-256` header on every incoming request. +::: diff --git a/en/docs/develop/integration-artifacts/event/github-webhooks.md b/en/docs/develop/integration-artifacts/event/github-webhooks.md index 990bbbeda77..1981712c8d4 100644 --- a/en/docs/develop/integration-artifacts/event/github-webhooks.md +++ b/en/docs/develop/integration-artifacts/event/github-webhooks.md @@ -1,20 +1,23 @@ --- title: GitHub Webhooks description: React to GitHub repository events — issues, pull requests, releases, pushes, and more — using pre-built event handlers for each event type. +keywords: [wso2 integrator, github webhooks, github event integration, webhook listener, issues, pull requests, releases] --- +import ThemedImage from '@theme/ThemedImage'; +import useBaseUrl from '@docusaurus/useBaseUrl'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # GitHub Webhooks -:::note -GitHub event integration is currently in **Beta**. +:::warning +GitHub event integration is currently in **Beta**. APIs and behavior may change in future releases. ::: GitHub event integrations receive webhook callbacks from GitHub and trigger handler functions as repository events occur. Use them to automate CI/CD workflows, sync issue trackers, enforce code review policies, and react to repository activity in real time. -## Creating a GitHub events service +## Creating a GitHub Events service @@ -23,7 +26,13 @@ GitHub event integrations receive webhook callbacks from GitHub and trigger hand 2. In the **Artifacts** panel, select **GitHub** under **Event Integration**. 3. In the creation form, fill in the following fields: - ![GitHub Event Integration creation form](/img/develop/integration-artifacts/event/github-webhooks/step-creation-form.png) + | Field | Description | Default | |---|---|---| @@ -41,7 +50,13 @@ GitHub event integrations receive webhook callbacks from GitHub and trigger hand 5. WSO2 Integrator opens the service in the **Service Designer**. The canvas shows the attached listener pill, the active event channel pill, and the **Event Handlers** section with all handlers for the selected channel pre-added. - ![Service Designer showing the GitHub Event Integration canvas](/img/develop/integration-artifacts/event/github-webhooks/step-service-designer.png) + All event handlers for the selected channel are added automatically. Click any handler to open it in the flow diagram view and implement the logic. @@ -55,39 +70,42 @@ import ballerina/log; configurable string webhookSecret = ?; configurable int port = 8090; -listener github:Listener githubListener = new (port, {webhookSecret: webhookSecret}); +listener github:Listener githubListener = new ( + listenerConfig = {webhookSecret: webhookSecret}, + listenOn = port +); service github:IssuesService on githubListener { - remote function onOpened(github:IssuesEvent event) returns error? { + remote function onOpened(github:IssuesEvent payload) returns error? { log:printInfo("Issue opened", - number = event.issue.number, - title = event.issue.title, - repo = event.repository.name); + number = payload.issue.number, + title = payload.issue.title, + repo = payload.repository.name); } - remote function onClosed(github:IssuesEvent event) returns error? { - log:printInfo("Issue closed", number = event.issue.number); + remote function onClosed(github:IssuesEvent payload) returns error? { + log:printInfo("Issue closed", number = payload.issue.number); } - remote function onReopened(github:IssuesEvent event) returns error? { - log:printInfo("Issue reopened", number = event.issue.number); + remote function onReopened(github:IssuesEvent payload) returns error? { + log:printInfo("Issue reopened", number = payload.issue.number); } - remote function onAssigned(github:IssuesEvent event) returns error? { - log:printInfo("Issue assigned", number = event.issue.number); + remote function onAssigned(github:IssuesEvent payload) returns error? { + log:printInfo("Issue assigned", number = payload.issue.number); } - remote function onUnassigned(github:IssuesEvent event) returns error? { - log:printInfo("Issue unassigned", number = event.issue.number); + remote function onUnassigned(github:IssuesEvent payload) returns error? { + log:printInfo("Issue unassigned", number = payload.issue.number); } - remote function onLabeled(github:IssuesEvent event) returns error? { - log:printInfo("Issue labeled", number = event.issue.number); + remote function onLabeled(github:IssuesEvent payload) returns error? { + log:printInfo("Issue labeled", number = payload.issue.number); } - remote function onUnlabeled(github:IssuesEvent event) returns error? { - log:printInfo("Issue unlabeled", number = event.issue.number); + remote function onUnlabeled(github:IssuesEvent payload) returns error? { + log:printInfo("Issue unlabeled", number = payload.issue.number); } } ``` @@ -102,7 +120,13 @@ In the **Service Designer**, click the **Configure** icon in the header to open -![GitHub Event Integration Configuration panel](/img/develop/integration-artifacts/event/github-webhooks/step-configuration.png) + The configuration panel has two sections. The top section configures the service and the bottom section configures the attached listener. @@ -129,8 +153,8 @@ Click **Save Changes** to apply updates. ```ballerina listener github:Listener githubListener = new ( - 8090, - {webhookSecret: webhookSecret} + listenerConfig = {webhookSecret: webhookSecret}, + listenOn = 8090 ); ``` @@ -166,100 +190,134 @@ When a GitHub Events service is created, WSO2 Integrator adds all handlers for t ### IssuesService handlers -| Handler | Triggered when | -|---|---| -| `onOpened` | A new issue is opened | -| `onClosed` | An issue is closed | -| `onReopened` | A closed issue is reopened | -| `onAssigned` | A user is assigned to an issue | -| `onUnassigned` | A user is unassigned from an issue | -| `onLabeled` | A label is added to an issue | -| `onUnlabeled` | A label is removed from an issue | +| Handler | Triggered when | Payload type | +|---|---|---| +| `onOpened` | A new issue is opened | `github:IssuesEvent` | +| `onClosed` | An issue is closed | `github:IssuesEvent` | +| `onReopened` | A closed issue is reopened | `github:IssuesEvent` | +| `onAssigned` | A user is assigned to an issue | `github:IssuesEvent` | +| `onUnassigned` | A user is unassigned from an issue | `github:IssuesEvent` | +| `onLabeled` | A label is added to an issue | `github:IssuesEvent` | +| `onUnlabeled` | A label is removed from an issue | `github:IssuesEvent` | ### PullRequestService handlers -| Handler | Triggered when | -|---|---| -| `onOpened` | A pull request is opened | -| `onClosed` | A pull request is closed or merged | -| `onReopened` | A closed pull request is reopened | -| `onAssigned` | A reviewer is assigned | -| `onUnassigned` | A reviewer is unassigned | -| `onLabeled` | A label is added | -| `onUnlabeled` | A label is removed | -| `onEdited` | A pull request title, body, or base branch is edited | -| `onReviewRequested` | A review is requested | -| `onReviewRequestRemoved` | A review request is removed | +| Handler | Triggered when | Payload type | +|---|---|---| +| `onOpened` | A pull request is opened | `github:PullRequestEvent` | +| `onClosed` | A pull request is closed or merged | `github:PullRequestEvent` | +| `onReopened` | A closed pull request is reopened | `github:PullRequestEvent` | +| `onAssigned` | A reviewer is assigned | `github:PullRequestEvent` | +| `onUnassigned` | A reviewer is unassigned | `github:PullRequestEvent` | +| `onLabeled` | A label is added | `github:PullRequestEvent` | +| `onUnlabeled` | A label is removed | `github:PullRequestEvent` | +| `onEdited` | A pull request title, body, or base branch is edited | `github:PullRequestEvent` | +| `onReviewRequested` | A review is requested | `github:PullRequestEvent` | +| `onReviewRequestRemoved` | A review request is removed | `github:PullRequestEvent` | ### IssueCommentService handlers -| Handler | Triggered when | -|---|---| -| `onCreated` | A comment is added to an issue or pull request | -| `onEdited` | An existing comment is edited | -| `onDeleted` | A comment is deleted | +| Handler | Triggered when | Payload type | +|---|---|---| +| `onCreated` | A comment is added to an issue or pull request | `github:IssueCommentEvent` | +| `onEdited` | An existing comment is edited | `github:IssueCommentEvent` | +| `onDeleted` | A comment is deleted | `github:IssueCommentEvent` | ### PullRequestReviewService handlers -| Handler | Triggered when | -|---|---| -| `onSubmitted` | A pull request review is submitted | -| `onDismissed` | A pull request review is dismissed | -| `onEdited` | A pull request review body is edited | +| Handler | Triggered when | Payload type | +|---|---|---| +| `onSubmitted` | A pull request review is submitted | `github:PullRequestReviewEvent` | +| `onDismissed` | A pull request review is dismissed | `github:PullRequestReviewEvent` | +| `onEdited` | A pull request review body is edited | `github:PullRequestReviewEvent` | ### PullRequestReviewCommentService handlers -| Handler | Triggered when | -|---|---| -| `onCreated` | A comment is added to a pull request diff | -| `onEdited` | A diff comment is edited | -| `onDeleted` | A diff comment is deleted | +| Handler | Triggered when | Payload type | +|---|---|---| +| `onCreated` | A comment is added to a pull request diff | `github:PullRequestReviewCommentEvent` | +| `onEdited` | A diff comment is edited | `github:PullRequestReviewCommentEvent` | +| `onDeleted` | A diff comment is deleted | `github:PullRequestReviewCommentEvent` | ### ReleaseService handlers -| Handler | Triggered when | -|---|---| -| `onPublished` | A release is published | -| `onUnpublished` | A release is unpublished | -| `onCreated` | A release draft is created | -| `onEdited` | A release is edited | -| `onDeleted` | A release is deleted | -| `onPreReleased` | A release is marked as a pre-release | -| `onReleased` | A pre-release is promoted to a full release | +| Handler | Triggered when | Payload type | +|---|---|---| +| `onPublished` | A release is published | `github:ReleaseEvent` | +| `onUnpublished` | A release is unpublished | `github:ReleaseEvent` | +| `onCreated` | A release draft is created | `github:ReleaseEvent` | +| `onEdited` | A release is edited | `github:ReleaseEvent` | +| `onDeleted` | A release is deleted | `github:ReleaseEvent` | +| `onPreReleased` | A release is marked as a pre-release | `github:ReleaseEvent` | +| `onReleased` | A pre-release is promoted to a full release | `github:ReleaseEvent` | ### LabelService handlers -| Handler | Triggered when | -|---|---| -| `onCreated` | A label is created in the repository | -| `onEdited` | A label name or color is changed | -| `onDeleted` | A label is deleted | +| Handler | Triggered when | Payload type | +|---|---|---| +| `onCreated` | A label is created in the repository | `github:LabelEvent` | +| `onEdited` | A label name or color is changed | `github:LabelEvent` | +| `onDeleted` | A label is deleted | `github:LabelEvent` | ### MilestoneService handlers -| Handler | Triggered when | -|---|---| -| `onCreated` | A milestone is created | -| `onOpened` | A closed milestone is reopened | -| `onClosed` | A milestone is closed | -| `onEdited` | A milestone title or description is edited | -| `onDeleted` | A milestone is deleted | +| Handler | Triggered when | Payload type | +|---|---|---| +| `onCreated` | A milestone is created | `github:MilestoneEvent` | +| `onOpened` | A closed milestone is reopened | `github:MilestoneEvent` | +| `onClosed` | A milestone is closed | `github:MilestoneEvent` | +| `onEdited` | A milestone title or description is edited | `github:MilestoneEvent` | +| `onDeleted` | A milestone is deleted | `github:MilestoneEvent` | ### PushService handlers -| Handler | Triggered when | -|---|---| -| `onPush` | Commits are pushed to a branch or a tag is created or deleted | +| Handler | Triggered when | Payload type | +|---|---|---| +| `onPush` | Commits are pushed to a branch or a tag is created or deleted | `github:PushEvent` | ### ProjectCardService handlers -| Handler | Triggered when | -|---|---| -| `onCreated` | A card is added to a project board | -| `onEdited` | A card note is edited | -| `onMoved` | A card is moved to a different column | -| `onConverted` | A card note is converted to an issue | -| `onDeleted` | A card is deleted from a project board | +| Handler | Triggered when | Payload type | +|---|---|---| +| `onCreated` | A card is added to a project board | `github:ProjectCardEvent` | +| `onEdited` | A card note is edited | `github:ProjectCardEvent` | +| `onMoved` | A card is moved to a different column | `github:ProjectCardEvent` | +| `onConverted` | A card note is converted to an issue | `github:ProjectCardEvent` | +| `onDeleted` | A card is deleted from a project board | `github:ProjectCardEvent` | + +:::info +Payload types for services other than `IssuesService` are inferred from the trigger package naming convention. Verify all types against the `ballerinax/trigger.github` source before relying on them in production code. +::: + +## Error handling + +If an event handler returns an error, the GitHub listener logs the error and continues processing subsequent events. Use `do/on fail` inside each handler to catch and recover from expected failures without propagating them to the listener. + + + + +Add an **Error Handler** block inside the handler flow to define recovery logic. Errors that escape the handler are caught by the listener and logged automatically. + + + + +```ballerina +service github:IssuesService on githubListener { + + remote function onOpened(github:IssuesEvent payload) returns error? { + do { + log:printInfo("Issue opened", number = payload.issue.number); + } on fail error err { + log:printError("Failed to handle onOpened event", err); + } + } +} +``` + +Return `error?` from a handler to allow unhandled errors to propagate to the listener. Return `()` to suppress them. + + + ## What's next @@ -267,3 +325,4 @@ When a GitHub Events service is created, WSO2 Integrator adds all handlers for t - [Salesforce Events](salesforce-events.md) — listen to Salesforce Change Data Capture events - [Connections](../supporting/connections.md) — reuse GitHub credentials across services - [GitHub connector reference](../../../connectors/catalog/developer-tools/github/connector-overview.md) — full connector API reference +- [Setup Guide](../../../connectors/catalog/developer-tools/github/setup-guide.md) — create a GitHub Personal Access Token and configure a repository webhook