🚀 How to Create Your Own GitHub App (Step-by-Step Guide)

Author: Mark Wayne B. Menorca
Organization: Cloudmateria / Wayne Enterprise Solution Corporation
Last Updated: October 2025

---

🧠 Overview

A GitHub App lets you integrate automation, CI/CD, bots, or custom workflows directly into GitHub — with granular permissions and event-based webhooks.

You can use a GitHub App to:

• Automate code scanning or validation
• Manage issues, pull requests, and commits
• Add custom status checks or CI gates
• Integrate with your internal systems (like Slack, Notion, or servers)
• Implement custom rules (e.g., prevent committing .env files)

In this guide, we’ll build a real GitHub App from scratch — deploy it, and make it perform automated tasks (like scanning for .env files) using Node.js + Express + Octokit.

---

🧩 Prerequisites

Before you start, make sure you have:

• A GitHub account or organization
• Node.js ≥ 18 installed
• Basic knowledge of JavaScript and npm
• A server or cloud platform (Render, Railway, Vercel, or VPS) with HTTPS

---

🧱 Step 1: Create a New GitHub App

1. Go to your GitHub Developer Settings page:
   👉 https://github.com/settings/apps/new

2. Fill in the required information:

Field	Description	Example
GitHub App name	A unique name for your app	Cloudmateria EnvGuard
Homepage URL	Your app’s homepage	https://yourapp.onrender.com
Callback URL	Required, even if unused (OAuth placeholder)	https://yourapp.onrender.com/auth
Webhook URL	The URL where GitHub will send webhook events	https://yourapp.onrender.com/github/webhook
Webhook Secret	Random secure string for verifying authenticity	gh_secret_12345

---

📜 Permissions

Under Repository Permissions, choose what your app needs access to:

Permission	Access Level	Purpose
Checks	Read & Write	To post Check Runs (status checks)
Issues	Read & Write	To create or comment on issues
Contents	Read-only	To analyze commits and file changes
Pull requests	Read-only	To respond to PRs
Metadata	Read-only	Always required

---

🔔 Subscribe to Events

Scroll to Subscribe to Events, and check:

• ✅ push
• ✅ pull_request

Click Create GitHub App.

---

🔑 Step 2: Generate Your App Credentials

After creating the app:

1. Download Private Key (.pem)
   This is your app’s authentication key (used to sign JWTs).
   Save it securely — never commit it to GitHub.

2. Note down these values:

   • App ID
   • Client ID
   • Webhook Secret
   • Your downloaded github-app.pem

---

☁️ Step 3: Deploy a Simple Node.js Server

Let’s build the backend to receive webhooks and process them.

1️⃣ Initialize project

mkdir my-github-app
cd my-github-app
npm init -y
npm install express @octokit/app @octokit/webhooks dotenv

2️⃣ Create .env

GITHUB_APP_ID=123456
GITHUB_WEBHOOK_SECRET=your_secret
PORT=3000

3️⃣ Create server.js

import express from "express";
import { App } from "@octokit/app";
import { Webhooks } from "@octokit/webhooks";
import dotenv from "dotenv";

dotenv.config();
const app = express();
app.use(express.json());

// 🗝️ Private key (load from environment)
const privateKey = process.env.GITHUB_PRIVATE_KEY?.replace(/\\n/g, "\n");

const githubApp = new App({
  appId: process.env.GITHUB_APP_ID,
  privateKey,
});

const webhooks = new Webhooks({
  secret: process.env.GITHUB_WEBHOOK_SECRET,
});

// ✅ Webhook route (modern Node 18+ compatible)
app.post("/github/webhook", async (req, res) => {
  try {
    await webhooks.verifyAndReceive({
      id: req.headers["x-github-delivery"],
      name: req.headers["x-github-event"],
      signature: req.headers["x-hub-signature-256"],
      payload: req.body,
    });
    res.status(200).send("Webhook received ✅");
  } catch (error) {
    console.error("❌ Webhook verification failed:", error.message);
    res.status(400).send("Invalid signature");
  }
});

// 🧩 Example event listener
webhooks.on(["push", "pull_request"], async ({ payload }) => {
  console.log("📦 Received event:", payload.action || "push");
});

app.listen(process.env.PORT || 3000, () => {
  console.log(`🚀 GitHub App listening on port ${process.env.PORT || 3000}`);
});

---

🧭 Step 4: Configure Your App URLs

In your GitHub App settings, go to General → Webhook:

Field	Value
Webhook URL	https://yourapp.onrender.com/github/webhook
Webhook Secret	same as .env
Callback URL	https://yourapp.onrender.com/auth (placeholder)

---

☁️ Step 5: Deploy to Render (or another host)

Render Example:

1. Go to Render.com
2. Click New → Web Service
3. Connect your GitHub repository
4. Build Command → npm install
   Start Command → node server.js
5. Add Environment Variables:
   • GITHUB_APP_ID
   • GITHUB_WEBHOOK_SECRET
   • GITHUB_PRIVATE_KEY (paste full PEM content)

Render automatically gives you a live HTTPS URL like:

https://yourapp.onrender.com

---

🧪 Step 6: Test It

1. Go to your GitHub App → Install App
2. Install it on a test repository
3. Push a commit or open a PR
4. Check your Render logs — you should see:

   📦 Received event: push
   Webhook received ✅
   

---

🧱 Step 7: Add Functionality

Now that your app receives webhooks, you can extend it!

Example: Create an Issue Automatically

webhooks.on("push", async ({ payload }) => {
  const { repository, installation } = payload;
  const owner = repository.owner.login;
  const repo = repository.name;

  const octokit = await githubApp.getInstallationOctokit(installation.id);
  await octokit.request("POST /repos/{owner}/{repo}/issues", {
    owner,
    repo,
    title: "🚨 New Push Event Detected",
    body: "This issue was created automatically by your GitHub App.",
  });

  console.log(`🧾 Issue created in ${owner}/${repo}`);
});

---

🔒 Step 8: Add a Custom Status Check

await octokit.request("POST /repos/{owner}/{repo}/check-runs", {
  owner,
  repo,
  name: "Custom Validation Check",
  head_sha: payload.after,
  status: "completed",
  conclusion: "success",
  output: {
    title: "✅ Custom Check Passed",
    summary: "Everything looks good!",
  },
});

This will appear under the Checks tab in the pull request.

---

🧾 Step 9: Enforce Merge Rules

In your repository:

1. Go to Settings → Branches → Branch Protection Rules
2. Enable:
   • ✅ Require status checks to pass before merging
   • ✅ Select your app’s check (e.g. “Custom Validation Check”)
3. Save → GitHub now blocks merges until your app’s check passes.

---

🧹 Step 10: Secure and Maintain

Task	Frequency	Description
🔑 Rotate PEM key	Every 6–12 months	Regenerate from GitHub App settings
🧰 Monitor logs	Weekly	Check webhook delivery reports
🚫 Never commit PEM	Always	Add to .gitignore
🔐 Use environment secrets	Always	Store credentials in Render/Host env vars
🧩 Test webhook delivery	On new deploy	Use GitHub “Recent Deliveries” panel

---

🧠 Example .gitignore

# Node and credentials
node_modules/
.env
*.pem

---

🧾 Common Issues

Error	Cause	Solution
Invalid signature	Webhook secret mismatch	Ensure GitHub App secret matches .env
argument handler must be a function	Old middleware version	Use verifyAndReceive() instead
Required status check missing	Wrong check name in protection rules	Update rule to match your check name
Webhook not received	Wrong webhook URL	Use full HTTPS Render URL + /github/webhook

---

✅ Summary

Step	Description
1️⃣	Create a new GitHub App
2️⃣	Set permissions & webhook events
3️⃣	Download private key (.pem)
4️⃣	Build Node.js backend with Octokit
5️⃣	Deploy on Render or Railway
6️⃣	Install the App on repositories
7️⃣	Add automation: issues, checks, alerts
8️⃣	Add branch protection for enforced security

---

📎 References

• GitHub Apps Documentation
• GitHub REST API
• @octokit/app
• @octokit/webhooks
• Render Docs

---

🏁 Conclusion

Creating your own GitHub App allows you to automate your workflows securely and at scale.
Whether it’s running checks, creating issues, or scanning commits, a self-hosted GitHub App gives you complete control over your development pipeline — with zero dependency on external services.

Once you’ve mastered this foundation, you can extend your app with:

• AI-driven code reviews
• Automated pull request templates
• Secret scanning (like EnvGuard)
• Slack or Discord notifications

Build once — automate forever. ⚙️💡