Skip to content

Commit 3f8ad4c

Browse files
chakravarthyBatnaWavemakerchakravarthyBatnaWavemaker
committed
Added GitHub Apps blog for wme and wmo
1 parent 5aa2fe7 commit 3f8ad4c

25 files changed

Lines changed: 300 additions & 0 deletions

‎learn/on-premise/configure/github-app-setup.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
---
2+
title: "GitHub App Setup for WaveMaker Enterprise (WME)"
3+
id: "github-app-setup"
4+
sidebar_label: "GitHub App Setup"
5+
---
6+
---
7+
8+
**Author: Chakravarthy Batna**
9+
10+
## Why Create a GitHub App?
11+
12+
In WaveMaker Enterprise, users connect to GitHub by creating a **Code Repository** (a VCS account) in the Team Portal. While creating a Code Repository, the user can authenticate with either a **Personal Access Token (PAT)** or a **GitHub App**.
13+
14+
Unlike WaveMaker Online — which comes with a ready-made, WaveMaker-managed GitHub App — WME is a **self-hosted deployment running in the customer's own environment**. There is no central GitHub App that the platform can ship with, because every WME installation runs under a different domain. The GitHub App's OAuth callback and post-installation URLs must point to that specific WME instance, which only the customer knows.
15+
16+
So before users can pick **GitHub App** as the authentication method in the Team Portal, a WME administrator has to do a **one-time setup**:
17+
18+
1. **Create a GitHub App** on [GitHub](https://github.com) under a personal account or organization, configured with the WME instance's callback URLs and the required permissions.
19+
2. **Register that GitHub App in WME LaunchPad** by providing the App ID, Client ID, Client Secret, and Private Key generated on GitHub.
20+
21+
Once both steps are done, the registered GitHub App becomes available to **all existing and newly created teams** in the Team Portal, and any team can use it to create Code Repositories — without ever generating a PAT.
22+
23+
The rest of this document walks through that one-time admin setup, and then how the GitHub App is used by end-users in the Team Portal.
24+
25+
---
26+
27+
## How to Create a GitHub App
28+
29+
Before connecting WME LaunchPad to GitHub, you need to create a GitHub App and collect the following credentials:
30+
31+
| Field | Where to find it |
32+
|-------------------|---------------------------------------------|
33+
| **App ID** | GitHub App settings page (auto-generated) |
34+
| **Client ID** | GitHub App settings page (auto-generated) |
35+
| **Client Secret** | Generated once after app creation |
36+
| **Private Key** | Generated and downloaded after app creation |
37+
38+
### Step 1 — Open the GitHub App Creation Page
39+
40+
A GitHub App can be created either under your **personal user account** or under an **organization account**. Choose
41+
based on who will own and manage the app.
42+
43+
#### Option A — Create under your Personal Account
44+
45+
Use this if you want the app to be owned by your individual GitHub user account.
46+
47+
> **Profile picture → Settings → Developer settings → GitHub Apps → New GitHub App**
48+
49+
#### Option B — Create under an Organization
50+
51+
Use this if you want the app to be owned by a GitHub organization (recommended for teams and production deployments).
52+
53+
> **Profile picture → Your organizations → Select your organization → Settings → Developer Settings → GitHub Apps → New
54+
GitHub App**
55+
56+
### Step 2 — Fill in Basic Information
57+
58+
![Create GitHub App - Basic Info form](/learn/assets/wme-create-github-app-basic-info-form.png)
59+
60+
| Field | Value |
61+
|---------------------|---------------------------------------------------------------------|
62+
| **GitHub App name** | Choose a unique name (e.g., `WaveMaker-Studio-App`) |
63+
| **Description** | *(Optional)* A short description shown to users during installation |
64+
| **Homepage URL** | Your WME Studio base URL (e.g., `https://<your-wme-domain>`) |
65+
66+
### Step 3 — Configure Callback URLs
67+
68+
Callback URLs are where GitHub redirects users after they authorize your app via OAuth. WME requires **two** callback
69+
URLs.
70+
71+
![Callback URL configuration](/learn/assets/wme-callback-urls-.png)
72+
73+
Replace `<your-wme-domain>` with your actual WME Studio domain, then click **Add Callback URL** to add each one:
74+
75+
**Callback URL 1:**
76+
77+
```
78+
https://<your-wme-domain>/edn-services/rest/github-apps/oauth/callback
79+
```
80+
81+
**Callback URL 2:**
82+
83+
```
84+
https://<your-wme-domain>/edn-services/rest/github-apps/oauth/default/callback
85+
```
86+
87+
Make sure **Expire user authorization tokens** is **checked** — this enables refresh tokens for long-lived sessions.
88+
89+
### Step 4 — Configure Post Installation URL
90+
91+
![Post installation Setup URL](/learn/assets/wme-post-installation-url.png)
92+
93+
Under the **Post installation** section, set the **Setup URL** to:
94+
95+
```
96+
https://<your-wme-domain>/edn-services/rest/github-apps/installations/callback
97+
```
98+
99+
### Step 5 — Webhook
100+
101+
![Webhook configuration](/learn/assets/wme-webhooks.png)
102+
103+
**Uncheck the Active checkbox** under the Webhook section — WME does not require GitHub webhooks for the LaunchPad
104+
integration.
105+
106+
### Step 6 — Set Repository Permissions
107+
108+
This is the most important step. Under **Permissions → Repository permissions**, set:
109+
110+
![Repository Permissions](/learn/assets/wme-permissions.png)
111+
112+
| Permission | Access Level | Why it's needed |
113+
|--------------------|--------------------|--------------------------------------------------------------------------------------------|
114+
| **Contents** | **Read and write** | Allows WME to read and write source code, commits, branches, releases, and perform merges |
115+
| **Pull requests** | **Read and write** | Allows WME to create and manage pull requests, comments, labels, and merges |
116+
| **Administration** | **Read and write** | Allows WME to create and manage repositories, configure settings, teams, and collaborators |
117+
118+
> **Metadata** (Read-only) is automatically granted and mandatory for all GitHub Apps.
119+
120+
### Step 7 — Set Installation Scope
121+
122+
![Installation scope](/learn/assets/wme-installation-scope.png)
123+
124+
At the bottom of the page, choose where this app can be installed:
125+
126+
- **Only on this account** — Restricts the app to your personal account or organization only. Suitable for
127+
private/internal use.
128+
- **Any account** — Allows any GitHub user or organization to install this app.
129+
130+
### Step 8 — Create the App
131+
132+
Click the green **Create GitHub App** button. GitHub will redirect you to your new app's settings page. The **App ID**
133+
and **Client ID** are shown at the top — **save these values**.
134+
135+
### Step 9 — Generate a Client Secret
136+
137+
![Generate Client Secret](/learn/assets/wme-client-secret.png)
138+
139+
1. On the app settings page, scroll to the **Client secrets** section.
140+
2. Click **Generate a new client secret**.
141+
3. Copy the secret immediately — **GitHub will only show it once**.
142+
4. Store it securely (password manager or secrets vault).
143+
144+
### Step 10 — Generate a Private Key
145+
146+
![Generate Private Key](/learn/assets/wme-private-keys.png)
147+
148+
1. Scroll down to the **Private keys** section.
149+
2. Click **Generate a private key**.
150+
3. A `.pem` file will be automatically downloaded.
151+
4. Keep this file secure — it cannot be retrieved again from GitHub.
152+
153+
---
154+
155+
## Register Credentials in WME LaunchPad
156+
157+
Once you have all four credentials, navigate to:
158+
159+
> **LaunchPad → Identity Providers → GitHub Apps → Register GitHub App**
160+
161+
In the registration form, enter the four credentials you collected — **App ID**, **Client ID**, **Client Secret**, and **Private Key** — and save.
162+
163+
![Register GitHub App in LaunchPad](/learn/assets/wme-register-github-app-launchpad.png)
164+
165+
After saving, the newly registered GitHub App appears in the **GitHub Apps** list in LaunchPad. From here, it becomes available to all existing teams and newly created teams for Code Repository creation.
166+
167+
![GitHub Apps list in LaunchPad](/learn/assets/wme-list-github-apps-launchpad.png)
168+
169+
---
170+
171+
## Using the GitHub App in the Team Portal
172+
173+
After the GitHub App is registered in LaunchPad, it becomes available to **all teams** in the Team Portal. Any team can now create a Code Repository using **GitHub App** as the authentication method — no further setup is required.
174+
175+
The end-user flow (selecting GitHub App, authorizing, installing, choosing repositories, and updating an installation later) is identical to WaveMaker Online. Refer to:
176+
177+
> **[GitHub App Integration in WaveMaker Platform](../../teams/github-app-integration.md)** — covers what a GitHub App is, how to create a Code Repository using GitHub App, and how to update an existing GitHub App installation from the Team Portal.

‎learn/teams/github-app-integration.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
title: "GitHub App Integration"
3+
id: "github-app-integration"
4+
sidebar_label: "GitHub App Integration"
5+
---
6+
---
7+
8+
**Author: Chakravarthy Batna**
9+
10+
The WaveMaker Platform supports **GitHub App-based authentication** for connecting your projects to GitHub repositories. This document explains what a GitHub App is, how the integration works in the WaveMaker Platform, and how to use it from the Team Portal.
11+
12+
---
13+
14+
## What is a GitHub App?
15+
16+
A **GitHub App** is an application registered on GitHub and installed into a user account or an organization to interact with GitHub repositories on their behalf. It acts as an independent identity on GitHub — separate from any individual user — and is granted scoped permissions on specific repositories chosen at installation time.
17+
18+
GitHub Apps use short-lived installation tokens that are issued and renewed automatically by GitHub. The application that consumes the GitHub App (in this case, the WaveMaker Platform) uses these tokens to perform repository operations such as cloning code, pushing commits, creating branches, and opening pull requests.
19+
20+
### How it fits in the WaveMaker Platform
21+
22+
Earlier, when a user wanted to create or connect a Code Repository in the Team Portal using GitHub, the only available option was a **Personal Access Token (PAT)**. With a PAT, the user had to:
23+
24+
- Generate a long token (`ghp_...`) from GitHub's **Developer Settings**.
25+
- Provide the token along with their GitHub username while creating the Code Repository.
26+
- Regenerate and reconfigure the token periodically when it expired.
27+
28+
The Team Portal now also supports a **GitHub App** as an authentication method while creating a Code Repository, giving users a credential-free alternative to PAT. The WaveMaker Platform ships with a pre-configured, WaveMaker-managed GitHub App, so users only need to install and authorize it against their own GitHub account or organization.
29+
30+
### Key Features of GitHub Apps
31+
32+
- **Short-lived, auto-rotated credentials.** Installation tokens are issued and renewed by GitHub automatically, removing the need to manually generate or refresh access credentials.
33+
- **Fine-grained repository access.** During installation, the owner can grant access to *all repositories* or only a *selected set*, ensuring the integration only sees what it needs.
34+
- **Granular permissions.** Each GitHub App declares the exact set of repository permissions it requires (e.g., Contents, Pull requests, Administration). These are displayed clearly during installation.
35+
- **Independent of any individual user.** A GitHub App is installed on a user or organization account rather than tied to a specific user's credentials, so the integration continues to work even if team members change.
36+
- **Designed for organization-level workflows.** GitHub Apps fit naturally into team and enterprise setups, where multiple repositories and members need to share the same integration.
37+
- **Clear audit trail.** Actions performed via a GitHub App are attributed to the app itself, making it easy to distinguish platform actions from user actions in the repository history.
38+
- **Simplified user experience.** Users connect their repositories through a guided installation flow on GitHub — no tokens to generate, copy, or store.
39+
40+
---
41+
42+
## How to Integrate GitHub App in Team Portal
43+
44+
In the WaveMaker Platform, users connect to GitHub by creating a **Code Repository** (a VCS account) under:
45+
46+
> **Team Portal → Code Repository**
47+
48+
While creating a Code Repository, the user chooses an authentication method — either **Personal Access Token (PAT)** or **GitHub App** — and can mark it as the **default**. From then on, whenever the user creates a repository, pushes, pulls, or performs any other VCS operation, the platform uses this Code Repository to talk to GitHub.
49+
50+
The WaveMaker Platform ships with a **pre-configured, WaveMaker-managed GitHub App**, so users do **not** need to create or register their own GitHub App. When a user wants to connect to GitHub via a GitHub App, they simply select **GitHub App** as the authentication method while creating the Code Repository, authorize the WaveMaker GitHub App, and pick the repositories it can access.
51+
52+
### Step 1 — Choose GitHub as the VCS Provider
53+
54+
Navigate to:
55+
56+
> **Team Portal → Code Repository → Add Code Repository**
57+
58+
In the **Choose Provider** step, select **GitHub** as the VCS provider.
59+
60+
### Step 2 — Configure Authentication
61+
62+
- Select **Authentication Method** as **GitHub App**.
63+
- Choose the required **Authentication Mode**:
64+
- **Team Credentials** — shared authorization used for team-wide repository operations.
65+
- **Developer Credentials** — repository operations are performed using each developer's own GitHub identity.
66+
note :
67+
- select wmo-code-connect github app
68+
- Click **Install GitHub App**.
69+
70+
![Choose authentication method](/learn/assets/wmo-choose-authentication-method.png)
71+
72+
### Step 3 — Authorize the GitHub App
73+
74+
You will be redirected to GitHub's authorization page, which displays the permissions requested by the WaveMaker GitHub App. Click **Authorize** to continue.
75+
76+
![Authorize the GitHub App](/learn/assets/wmo-authorize-github-app.png)
77+
78+
### Step 4 — Install the GitHub App
79+
80+
After authorization, GitHub redirects you to the GitHub App installation page. Here you can:
81+
82+
- Select the personal GitHub account or organization where the app should be installed.
83+
- Choose whether the app should access **All repositories** or **Only selected repositories**.
84+
85+
> **Note:** If you choose **Only selected repositories**, the WaveMaker Platform will be able to access **only those repositories** — it cannot see or operate on any other repository in your account or organization. To grant access to more repositories later, you must update the GitHub App installation settings on GitHub.
86+
87+
Once the installation is complete, the popup closes automatically and you are returned to the platform.
88+
89+
![GitHub App installation page](/learn/assets/wmo-installation-page.png)
90+
91+
![Choosing repositories](/learn/assets/wmo-choosing-repos.png)
92+
93+
### Step 5 — Select Repository Location
94+
95+
The platform automatically fetches available GitHub App installations. Select the GitHub **account** or **organization** that was previously authorized and installed.
96+
97+
![Select organization](/learn/assets/wmo-select-organization.png)
98+
99+
Once the installation (organization or account) is selected, continue with the remaining steps in the **Add Code Repository** wizard and **save** the Code Repository. The selected installation will be used for repository creation and all subsequent VCS operations.
100+
101+
---
102+
103+
## Updating a GitHub App Installation
104+
105+
If you have unintentionally **uninstalled** the WaveMaker GitHub App from the GitHub user or organization account that was configured in a Code Repository (VCS account), the platform will no longer be able to access those repositories. You can re-install the app and update the existing Code Repository without creating a new one.
106+
107+
To update the installation:
108+
109+
1. Navigate to **Team Portal → Code Repository**.
110+
2. Locate the Code Repository whose installation you want to update.
111+
3. Click the **Credentials** button on that Code Repository.
112+
4. Click **Update GitHub App Installation**.
113+
5. You will be redirected to GitHub to re-install the WaveMaker GitHub App. Choose the same account/organization and repositories as before.
114+
6. Once installation is complete, the Code Repository will be reconnected automatically.
115+
116+
![Update GitHub App Installation](/learn/assets/wmo-update-github-app-installation.png)

‎website/sidebars.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -663,6 +663,7 @@
663663
"teams/project-branch",
664664
"teams/manage-roles",
665665
"teams/code-repository",
666+
"teams/github-app-integration",
666667
"how-tos/azure-repos-vcs",
667668
"teams/import-vcs-project",
668669
"teams/team-profile",
@@ -729,6 +730,7 @@
729730
"on-premise/aws/install/apply-license",
730731
"on-premise/configure/config-users-auth-providers",
731732
"on-premise/configure/config-vcs",
733+
"on-premise/configure/github-app-setup",
732734
"on-premise/configure/add-dev-capacity",
733735
"on-premise/configure/add-apps-capacity",
734736
"on-premise/configure/config-pipeline"
@@ -750,6 +752,7 @@
750752
"on-premise/azure/install/apply-license",
751753
"on-premise/configure/config-users-auth-providers",
752754
"on-premise/configure/config-vcs",
755+
"on-premise/configure/github-app-setup",
753756
"on-premise/configure/add-dev-capacity",
754757
"on-premise/configure/add-apps-capacity",
755758
"on-premise/configure/config-pipeline"
@@ -770,6 +773,7 @@
770773
"on-premise/gcp/install/apply-license",
771774
"on-premise/configure/config-users-auth-providers",
772775
"on-premise/configure/config-vcs",
776+
"on-premise/configure/github-app-setup",
773777
"on-premise/configure/add-dev-capacity",
774778
"on-premise/configure/add-apps-capacity",
775779
"on-premise/configure/config-pipeline"
@@ -791,6 +795,7 @@
791795
"on-premise/vmware-esxi/install/apply-license",
792796
"on-premise/configure/config-users-auth-providers",
793797
"on-premise/configure/config-vcs",
798+
"on-premise/configure/github-app-setup",
794799
"on-premise/configure/add-dev-capacity",
795800
"on-premise/configure/add-apps-capacity",
796801
"on-premise/configure/config-pipeline"
@@ -811,6 +816,7 @@
811816
"on-premise/hyper-v/install/apply-license",
812817
"on-premise/configure/config-users-auth-providers",
813818
"on-premise/configure/config-vcs",
819+
"on-premise/configure/github-app-setup",
814820
"on-premise/configure/add-dev-capacity",
815821
"on-premise/configure/add-apps-capacity",
816822
"on-premise/configure/config-pipeline"
@@ -822,6 +828,7 @@
822828
"items": [
823829
"on-premise/configure/config-users-auth-providers",
824830
"on-premise/configure/config-vcs",
831+
"on-premise/configure/github-app-setup",
825832
"on-premise/configure/add-dev-capacity",
826833
"on-premise/configure/add-apps-capacity",
827834
"on-premise/configure/config-pipeline",

‎website/static/learn/assets/wme-authorize-github-app.png‎

101 KB
Loading

‎website/static/learn/assets/wme-callback-urls-.png‎

94.1 KB
Loading

‎website/static/learn/assets/wme-choose-authentication-method.png‎

66.2 KB
Loading

‎website/static/learn/assets/wme-choosing-repos.png‎

98.9 KB
Loading

‎website/static/learn/assets/wme-client-secret.png‎

13.7 KB
Loading

‎website/static/learn/assets/wme-create-github-app-basic-info-form.png‎

39.9 KB
Loading

‎website/static/learn/assets/wme-installation-page.png‎

72 KB
Loading

0 commit comments

Comments
 (0)