Git App Installation
Installation Flow Overview
1. Installation Initiation
When users need to connect repositories, they initiate the GitHub App installation process:
- User clicks “Install GitHub App” or “Connect Repository”
- Application redirects to GitHub’s app installation page
- GitHub presents the installation interface with permission requests
2. GitHub Installation Page
GitHub displays the installation interface where users can:
- Select repositories (all repositories or specific ones)
- Review requested permissions
- Choose installation target (personal account or organization)
- Confirm installation
3. Installation Callback Handling
After installation, GitHub redirects to the callback URL with installation data:
Callback Route: /github-installed
// src/app/github-installed/page.tsx
export default function GitHubInstalled() {
const params = useSearchParams();
const [isLoading, startTransition] = useTransition();
useEffect(() => {
startTransition(async () => {
// Make API call to process installation
await fetch(`/api/auth/github?${params.toString()}`);
window.close(); // Close popup window
});
}, []);
}4. Installation Processing
The callback triggers the GitHub authentication API route:
Authentication Route: /api/auth/github
// src/app/api/auth/github/route.ts
async function handler(request: NextRequest) {
const { searchParams } = new URL(request.url);
const code = searchParams.get("code");
const installationId = searchParams.get("installation_id");
// Create GitHub App authentication
const octokit = new Octokit({
authStrategy: createAppAuth,
auth: {
appId: process.env.GITHUB_APP_ID!,
privateKey: process.env.GITHUB_APP_PRIVATE_KEY!,
installationId,
},
});
// Get installation token
const installation = await octokit.auth({
type: "installation",
});
// Create OAuth token
const app = new App({
oauth: {
clientId: process.env.GITHUB_APP_CLIENT_ID!,
clientSecret: process.env.GITHUB_APP_CLIENT_SECRET!,
},
appId: process.env.GITHUB_APP_ID!,
privateKey: process.env.GITHUB_APP_PRIVATE_KEY!,
});
const token = await app.oauth.createToken({ code: code! });
// Store provider information
await createProvider({
provider: "Github",
access_token: token.authentication.token,
token_type: installation.tokenType,
installation_access_token: installation.token,
userId: "",
});
}Authentication Types & Tokens
Installation Authentication
type GitHubAppInstallation = {
type: "token";
tokenType: "installation";
token: string; // Installation access token
installationId: number; // Unique installation identifier
permissions: {
contents: "write"; // Repository content access
metadata: "read"; // Repository metadata access
administration: "write"; // Repository administration
pull_requests: "write"; // Pull request management
// ... additional permissions
};
repositorySelection: "all" | "selected";
createdAt: string; // ISO timestamp
expiresAt: string; // Token expiration
};OAuth Authentication
type GitHubAppOAuthAuthentication = {
type: "token";
tokenType: "oauth";
clientType: "github-app";
clientId: string;
clientSecret: string;
token: string; // OAuth access token
refreshToken: string; // Token refresh capability
expiresAt: string; // OAuth token expiration
refreshTokenExpiresAt: string; // Refresh token expiration
};Installation Scenarios
Personal Account Installation
- User installs app on their personal repositories
- Immediate access to selected repositories
- Installation completes instantly
Provider Data Storage
The installation process stores provider information through the createProvider action:
// src/actions/provider/index.ts
await createProvider({
provider: "Github", // Git provider type
access_token: token.authentication.token, // OAuth access token
expires_in: 0, // Token expiration
refresh_token_expires_in: 0, // Refresh expiration
token_type: installation.tokenType, // Token type identifier
installation_access_token: installation.token, // Installation token
userId: "", // Associated user ID
});Installation Permissions
The GitHub App requests specific permissions during installation:
Repository Permissions
- Contents: Read & Write access to repository files
- Metadata: Read access to repository information
- Administration: Write access for repository settings
- Pull Requests: Write access for collaboration features
- Actions: Write access for GitHub Actions
- Checks: Write access for status checks
- Statuses: Write access for commit statuses
Permission Validation
The installation process validates that all required permissions are granted:
// Verify installation has required permissions
const requiredPermissions = [
"contents",
"metadata",
"administration",
"pull_requests",
];
const hasAllPermissions = requiredPermissions.every(
(permission) => installation.permissions[permission]
);Error Handling & Recovery
Installation Errors
try {
// Installation processing
} catch (error) {
console.error("GitHub installation error:", error);
return NextResponse.json(
{
error: error.message || "Installation failed",
},
{ status: 500 }
);
}Common Installation Issues
- Permission Denied: User lacks admin rights on repositories
- Organization Restrictions: Organization policies prevent installations
- Network Errors: Connectivity issues during installation
- Token Expiration: Authentication tokens expire during process
Post-Installation Flow
Successful Installation
- Provider data stored in backend
- User redirected to application
- Repository access becomes available
- User can begin content management
Installation Request
- Request logged for organization owner
- User notified of pending approval
- No immediate access granted
- Owner approval required for activation
Installation Security
Token Management
- Installation tokens have limited scope and expiration
- OAuth tokens enable user-level operations
- Refresh tokens provide long-term access
- All tokens stored securely in backend
Permission Isolation
- App only requests necessary permissions
- Repository access limited to installation scope
- User permissions validated on each request
- Installation can be revoked at any time
Integration with Application State
After successful installation:
- Config Update: Application config updated with repository information
- Provider Registration: GitHub provider registered in user account
- Repository Discovery: Available repositories loaded and cached
- UI Update: Application interface reflects new repository access
Last updated on