Personal GitHub tokens are convenient when a script, application, or CI pipeline needs to access GitHub. They are easy to create, easy to copy into a secret store, and usually work with the same APIs developers use interactively.
The problem appears when those tokens become part of an automation system.
A personal token is tied to a user account. If that account changes, the person leaves the team, the token expires, or the token gets exposed, automation can suddenly stop working or become a security concern.
GitHub Apps provide a different model. Instead of making automation authenticate as a person, an application can authenticate as itself and receive short-lived installation access tokens with specific permissions.
This makes GitHub Apps useful for CI/CD systems, internal tools, bots, integrations, and services that need to interact with repositories without depending on a developer's personal credentials.
Why Personal Tokens Become a Problem
Imagine a deployment script that uses a personal GitHub token.
env:
GITHUB_TOKEN: ${{ secrets.PERSONAL_GITHUB_TOKEN }}The workflow may work perfectly for months.
Then the developer who created the token:
leaves the organization
changes their permissions
revokes the token
rotates credentials
loses repository access
changes the scope of the token
The automation may stop working even though nothing changed in the application itself.
There is another problem.
The token represents the user.
If the automation only needs permission to read a repository, but the token belongs to an administrator with broad access, the automation effectively inherits permissions it does not need.
This creates unnecessary risk.
What Is a GitHub App?
A GitHub App is an application identity registered with GitHub.
Instead of saying:
This request comes from developer A.the system can authenticate as:
This request comes from deployment application B.The application can then be installed on selected repositories or organizations and granted specific permissions.
The authentication flow generally looks like this:
GitHub App
|
| App credentials
v
Create signed JWT
|
v
GitHub App API
|
| Installation access token
v
GitHub Repository APIThe important distinction is that the long-lived application credential is used to obtain a short-lived installation token.
That installation token is then used for GitHub API operations.
Personal Token vs GitHub App Authentication
The two approaches solve similar problems but have different security and operational models.
Area | Personal Token | GitHub App |
|---|---|---|
Identity | User | Application |
Tied to employee account | Yes | No |
Repository permissions | Depends on token configuration | Configured per app installation |
Short-lived API token | Usually not the main model | Yes |
Rotation concerns | User token management | App private key management |
Suitable for automation | Possible | Strong fit |
Audit identity | User | App |
Repository selection | Token-dependent | Installation-dependent |
Organization control | Depends on token | Centralized app management |
A personal token can still be appropriate for some individual developer workflows.
For long-running automation, GitHub Apps usually provide a cleaner identity boundary.
Start by Identifying What the Automation Actually Needs
Do not begin by creating a GitHub App with every available permission.
First inspect the automation.
For example, a workflow may need to:
read repository contents
create pull requests
add comments
read issues
create releases
manage workflow runs
read metadata
These are different capabilities.
A good migration starts by documenting the exact API operations.
For example:
Repository contents
Read
Pull requests
Write
Issues
Read
Actions
ReadThis becomes the permission model for the GitHub App.
The goal is not simply to replace one credential with another.
The goal is to reduce the permissions available to the automation.
Create the GitHub App
The GitHub App is registered in the GitHub account or organization that will manage it.
During setup, configure:
application name
application description
callback information if required
webhook settings if required
repository permissions
organization permissions
user permissions
For a service that only works with repository APIs, avoid enabling unrelated permissions.
For example, if the application only needs to read repository contents, there is no reason to grant write access to repository administration.
This principle becomes especially important when the app is used by CI/CD systems.
Install the App on the Required Repositories
Creating an app does not automatically give it access to every repository.
The app needs to be installed.
An installation can be limited to selected repositories.
For example:
Deployment App
Repositories:
application-api
application-webThe app does not need access to:
documentation
experiments
personal-project
internal-toolsunless the automation actually requires those repositories.
This repository-level boundary is one of the major advantages over broadly scoped personal credentials.
Store the App Private Key Securely
GitHub Apps use a private key for authentication.
The private key should be treated like any other sensitive credential.
Do not put it directly in the workflow file.
Bad:
env:
APP_PRIVATE_KEY: |
-----BEGIN PRIVATE KEY-----
actual-key
-----END PRIVATE KEY-----The private key should instead be stored in a protected secret store.
For GitHub Actions, it can be stored as a repository, organization, or environment secret depending on the required scope.
For example:
env:
APP_PRIVATE_KEY: ${{ secrets.GITHUB_APP_PRIVATE_KEY }}The workflow receives the key only when the authentication step needs it.
Understand the Authentication Flow
The GitHub App authentication flow has an important distinction between the app itself and its installation.
The private key identifies the application.
A signed JSON Web Token is then created using the app's credentials.
That JWT is used to request an installation access token.
The installation token is then used for API calls.
Conceptually:
Private Key
|
v
Signed JWT
|
v
Installation
|
v
Short-Lived Access Token
|
v
GitHub APIThis is different from simply putting a personal access token into an Authorization header.
Example With Node.js
A Node.js service can use a GitHub App with an SDK such as Octokit.
A simplified example looks like this:
const { App } = require("@octokit/app");
const app = new App({
appId: process.env.GITHUB_APP_ID,
privateKey: process.env.GITHUB_APP_PRIVATE_KEY
});
async function getRepository() {
const octokit = await app.getInstallationOctokit(
process.env.GITHUB_INSTALLATION_ID
);
const response = await octokit.request(
"GET /repos/{owner}/{repo}",
{
owner: "example-org",
repo: "example-repository"
}
);
console.log(response.data.full_name);
}
getRepository().catch(console.error);The application does not need a personal GitHub token.
The app obtains authentication based on its own identity and installation.
The exact SDK and implementation can vary, but the security model remains the same.
Example With GitHub Actions
A GitHub Actions workflow can also authenticate through a GitHub App.
A common design is:
name: Repository Automation
on:
workflow_dispatch:
permissions:
contents: read
jobs:
automation:
runs-on: ubuntu-latest
steps:
- name: Generate GitHub App token
id: app-token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ vars.GITHUB_APP_ID }}
private-key: ${{ secrets.GITHUB_APP_PRIVATE_KEY }}
- name: Call GitHub API
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
run: |
gh api repos/${{ github.repository }}The private key stays in GitHub Secrets.
The generated installation token is then used for the API operation.
The workflow does not need a developer's personal GitHub token.
Why Short-Lived Tokens Matter
A personal token may remain valid until it expires or is manually revoked.
An installation token is designed for short-term use.
That difference matters during a security incident.
Suppose a workflow token is accidentally exposed.
With a short-lived installation token, the window of opportunity is limited.
This does not mean exposure can be ignored. The credential should still be investigated and the app credentials reviewed.
But short-lived credentials reduce the value of keeping an exposed token around indefinitely.
Keep the Private Key Out of Logs
Moving from personal tokens to GitHub Apps does not automatically make a workflow secure.
The app private key is still a secret.
Never do this:
- name: Debug authentication
run: |
echo "$GITHUB_APP_PRIVATE_KEY"Also avoid:
envor:
printenvwhen the private key is present in the environment.
The same logging rules used for other secrets apply to GitHub App credentials.
Use Environment Variables Carefully
A useful pattern is to expose sensitive values only to the step that needs them.
Instead of:
jobs:
deploy:
env:
GITHUB_APP_PRIVATE_KEY: ${{ secrets.GITHUB_APP_PRIVATE_KEY }}
steps:
- name: Build
run: npm run build
- name: Test
run: npm test
- name: GitHub API
run: ./github-api.sh
Join the conversation! Your thoughts help the community grow.