---

🧠 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

Feature	GitHub App	OAuth App
Authentication	JWT + Installation Token	OAuth token (user context)
Permissions	Granular per repo/org	Broad (user-level scopes)
Webhooks	App-specific	Shared via user
Recommended Use	Automation, integrations	User-based access

🔧 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);

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}`));

---

🤖 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

Feature	REST API	GraphQL API
Simplicity	Easier for simple tasks	More efficient querying
Flexibility	Fixed endpoints	Custom queries
App Support	Both supported	GraphQL works with JWT tokens

---

💡 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']
});

📢 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

Topic	Description
GitHub App	First-class automation/integration bot
Auth	JWT + Installation Token
Key Libraries	jsonwebtoken, probot, @octokit/rest
Key Features	Webhooks, fine-grained access, marketplace
Real-World Use Cases	Bots, CI/CD, Slack/Discord integrations

---

🧰 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

---