🧠 What is a GitHub App?

A GitHub App is a first-class actor in the GitHub ecosystem. Unlike OAuth apps which act on behalf of a user, GitHub Apps have granular permissions, are installable on organizations or repositories, and authenticate as themselves or as an installation.

They’re designed for automation, integrations, and custom workflows such as CI/CD, issue bots, custom pull request checks, and more.

🚀 Tutorial Roadmap

Section 1: GitHub App Basics

1. What is a GitHub App
2. GitHub App vs OAuth App
3. Use Cases
4. Basic GitHub App Architecture

Section 2: Building Your First GitHub App

1. Creating the GitHub App
2. Installing the App on a Repository
3. Authenticating the App (JWT & Installation Token)
4. Handling Webhooks
5. Sample Node.js App with Probot

Section 3: Advanced Concepts

1. Scopes and Permissions
2. Webhook Security and Verification
3. GitHub App Manifest Flow (for user-friendly installs)
4. GitHub APIs: REST vs GraphQL in GitHub Apps
5. Multi-repo & Org-level Access Management

Section 4: Real-World Use Cases

1. Auto-labeling Pull Requests
2. Slack Notifications on Issues
3. GitHub App for CI/CD Trigger
4. GitHub App with Terraform Workflows
5. Marketplace App Deployment

🧩 Section 1: GitHub App Basics

✅ What is a GitHub App?

• GitHub App = A bot/integration that acts independently, with restricted and customizable access to your repositories and orgs.
• Supports webhooks, fine-grained permissions, and custom API interactions.

🔐 GitHub App vs OAuth App

🔧 Use Cases

• GitHub bot (like Mergify)
• Security scanners (e.g., Dependabot)
• CI/CD trigger tools
• PR auto-review and checks
• GitHub → Slack, Jira integrations

⚙️ Section 2: Building Your First GitHub App

📍 Step 1: Create a GitHub App

Go to: https://github.com/settings/apps

• App Name: my-first-gh-app
• Homepage URL: http://localhost:3000 or your project site
• Webhook URL: http://localhost:3000/webhooks
• Permissions:
  • Contents: Read-only
  • Issues: Read & write
  • Pull requests: Read & write
• Subscribe to Webhooks:
  • issues
  • pull_request

After creation, download the private key (PEM file) and note your:

• App ID
• Client ID & Secret
• Webhook Secret

🔐 Step 2: Authentication (JWT → Installation Token)

GitHub Apps authenticate using:

1. JWT (JSON Web Token) – signs requests as the App.
2. Installation Token – used to act on a specific repo/org installation.

🧪 Example: Generate JWT (Node.js)

const jwt = require("jsonwebtoken");
const fs = require("fs");

const APP_ID = "YOUR_APP_ID";
const PRIVATE_KEY = fs.readFileSync("private-key.pem");

const token = jwt.sign(
  {
    iat: Math.floor(Date.now() / 1000), // issued at
    exp: Math.floor(Date.now() / 1000) + (10 * 60), // expires in 10 min
    iss: APP_ID,
  },
  PRIVATE_KEY,
  { algorithm: "RS256" }
);

console.log(token);
Code language: JavaScript (javascript)

Use this JWT to call:

POST /app/installations/:installation_id/access_tokens

🔁 Step 3: Handle Webhooks

GitHub will send webhooks to your app for subscribed events.

const express = require("express");
const bodyParser = require("body-parser");
const crypto = require("crypto");

const app = express();
const PORT = 3000;
const WEBHOOK_SECRET = "your-webhook-secret";

app.use(bodyParser.json());

app.post("/webhooks", (req, res) => {
  const sig = req.headers["x-hub-signature-256"];
  const payload = JSON.stringify(req.body);

  const hmac = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(payload)
    .digest("hex");

  const expected = `sha256=${hmac}`;

  if (sig !== expected) {
    return res.status(401).send("Invalid signature");
  }

  console.log("Received event:", req.body.action);
  res.sendStatus(200);
});

app.listen(PORT, () => console.log(`Listening on port ${PORT}`));
Code language: JavaScript (javascript)

🤖 Step 4: Use Probot (Quick Start)

Probot is a framework to build GitHub Apps quickly.

npx create-probot-app my-github-app
cd my-github-app
npm start

This gives you a working app that responds to PRs or Issues.

📚 Section 3: Advanced Concepts

1. 🔐 Permissions

Choose carefully:

• Repository contents: Needed to read/write files
• Issues: Read/write for issue bots
• Metadata: Always needed to list repos

You can update permissions in the GitHub App settings or dynamically request permissions during manifest-based installs.

2. 🧪 Webhook Security Tips

• Always verify webhook signature
• Rate limit / retry safe
• Use GitHub’s IP allowlist for security

3. 🚀 GitHub App Manifest Flow

Use the manifest flow to allow users to easily install your GitHub App from a public-facing app.

Benefits:

• Avoid manual configuration
• Better UX for your app’s installation

Manifest Docs

4. 🔁 REST vs GraphQL APIs

💡 Section 4: Real-World Use Cases

🤖 Use Case 1: Auto-label Pull Requests

Label PRs based on title/author.

// listen to pull_request.opened and label accordingly
context.octokit.issues.addLabels({
  owner,
  repo,
  issue_number: context.payload.pull_request.number,
  labels: ['auto-labeled']
});
Code language: JavaScript (javascript)

📢 Use Case 2: Slack Notifications

Send a message to Slack on new issue creation via webhook logic.

🏗 Use Case 3: CI/CD GitHub App

Trigger a deployment pipeline from PR merges or release tags using app permissions and webhook events.

⚙ Use Case 4: App for Terraform Automation

A GitHub App can:

• Watch .tf file changes
• Run validation pipelines
• Comment back status on PR

💰 Use Case 5: Publish to GitHub Marketplace

Once stable, your GitHub App can be published as a Marketplace App to share with the world.

📌 Summary

🧰 Recommended Tools & Libraries

• Probot
• Octokit.js
• @actions/github
• GitHub CLI: gh app install

🔗 Want to Go Further?

• GitHub Apps Docs
• GitHub REST API
• Probot Examples

Rajesh Kumar

I’m a DevOps/SRE/DevSecOps/Cloud Expert passionate about sharing knowledge and experiences. I have worked at Cotocus. I share tech blog at DevOps School, travel stories at Holiday Landmark, stock market tips at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow , and SEO strategies at Wizbrand.

Do you want to learn Quantum Computing?

Please find my social handles as below;

Rajesh Kumar Personal Website
Rajesh Kumar at YOUTUBE
Rajesh Kumar at INSTAGRAM
Rajesh Kumar at X
Rajesh Kumar at FACEBOOK
Rajesh Kumar at LINKEDIN
Rajesh Kumar at WIZBRAND

Rajesh Kumar DailyLogs