🧠 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 Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.