github-oauth-nango-integration skill
✓ 인증됨Nango를 사용하여 GitHub 사용자 신원과 GitHub App 저장소 액세스를 분리하는 이중 연결 OAuth 패턴을 구현합니다.
- GitHub 스타
- 1,109
- 파일
- 1
- 마지막 커밋
- 2026년 11월 11일
- 라이선스
- Apache-2.0
- 허용된 도구
- —
github-oauth-nango-integration skill은 무엇을 하나요?
Nango를 사용하여 GitHub 사용자 신원과 GitHub App 저장소 액세스를 분리하는 이중 연결 OAuth 패턴을 구현합니다.
skill의 SKILL.md에서 생성된 요약입니다.
github-oauth-nango-integration skill 정보
사용자 인증과 저장소 관리가 모두 필요한 애플리케이션을 개발하는 경우, 이 통합 기능을 사용하여 신원과 액세스 권한 분리 문제를 해결할 수 있습니다. Nango를 사용하여 GitHub 사용자 신원과 GitHub App 저장소 액세스를 분리하는 이중 연결 패턴을 구현합니다. 이 방식을 통해 애플리케이션은 어떤 사용자가 로그인했는지 정확히 파악하는 동시에, GitHub App 설치를 통해 풀 리퀘스트, 커밋 또는 파일에 대한 세밀한 읽기 권한을 유지할 수 있습니다.
에이전트는 OAuth 사용자와 특정 저장소 권한을 일치시켜야 하는 시스템을 설정할 때 이 SKILL을 로드해야 합니다. 이 통합 기능은 두 가지 별도의 Nango 연결을 사용합니다. 이름 및 이메일과 같은 사용자 프로필을 위한 github 통합과 특정 저장소에 액세스하기 위한 github-app-oauth 통합입니다. 초기 로그인 흐름 및 웹훅 처리부터 풀 리퀘스트와 커밋을 위한 백그라운드 데이터 동기화까지 모든 과정을 처리하며, 사용자 ID를 저장소 설치와 연결하는 구조화된 방법을 제공합니다.
agent가 수행할 수 있는 작업
- 1사용자와 저장소 일치인증된 사용자 신원을 사용자가 승인한 특정 GitHub App 설치와 연결합니다.
skill의 SKILL.md를 기반으로 작성되었습니다. 모든 사용 사례는 해당 문서의 인용구와 대조 확인되었습니다.
github-oauth-nango-integration skill 설치 방법
각 명령은 skill 폴더를 클라이언트의 skills 디렉터리에 복사합니다. 클라이언트를 재시작하거나 새 세션을 시작하여 로드하세요.Claude Code에 github-oauth-nango-integration skill 설치
~/.claude/skills/github-oauth-nango-integration/SKILL.md
$ npx degit AgentWorkforce/relay/.claude/skills/github-oauth-nango-integration ~/.claude/skills/github-oauth-nango-integrationClaude Code (project)에 github-oauth-nango-integration skill 설치
.claude/skills/github-oauth-nango-integration/SKILL.md
$ npx degit AgentWorkforce/relay/.claude/skills/github-oauth-nango-integration .claude/skills/github-oauth-nango-integrationCodex에 github-oauth-nango-integration skill 설치
~/.agents/skills/github-oauth-nango-integration/SKILL.md
$ npx degit AgentWorkforce/relay/.claude/skills/github-oauth-nango-integration ~/.agents/skills/github-oauth-nango-integrationGemini CLI에 github-oauth-nango-integration skill 설치
~/.gemini/skills/github-oauth-nango-integration/SKILL.md
$ npx degit AgentWorkforce/relay/.claude/skills/github-oauth-nango-integration ~/.gemini/skills/github-oauth-nango-integrationClaude.ai에 github-oauth-nango-integration skill 설치
npx degit AgentWorkforce/relay/.claude/skills/github-oauth-nango-integration github-oauth-nango-integration && zip -r github-oauth-nango-integration.zip github-oauth-nango-integration # claude.ai → Customize → Skills → + → Create skill → Upload a skill → github-oauth-nango-integration.zip
자동 검사
2026년 11월 15일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 보안 감사는 아닙니다. 에이전트가 실행하기 전에 스크립트를 읽어 보세요. 검사 방식
- 소스 저장소 연결 및 접근 가능agentworkforce/relay/.claude/skills/github-oauth-nango-integration is public and reachablegithub.com/agentworkforce/relay/tree/HEAD/.claude/skills/git ↗통과
- 오픈 소스 라이선스 (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit 2026-11-11github.com/agentworkforce/relay/commits ↗통과
- 스크립트에 다운로드 후 실행이나 자격 증명 탈취가 없음No scripts in the skill folder통과
- SKILL.md에 숨겨진 지침 없음No override phrases, safeguard switches, credential requests or hidden charactersgithub.com/agentworkforce/relay/blob/HEAD/.claude/skills/git ↗통과
- 사전 허용 도구가 제한됨No pre-approved tools; the agent asks before using onegithub.com/agentworkforce/relay/blob/HEAD/.claude/skills/git ↗통과
- SKILL.md가 Agent Skills 형식을 따름Valid name and description; says when to use it; 410 linesgithub.com/agentworkforce/relay/blob/HEAD/.claude/skills/git ↗통과
SKILL.md
GitHub에서 보기GitHub OAuth + Nango Integration
Overview
Implements dual-connection OAuth pattern: one for user identity (github integration), another for repository access (github-app-oauth integration). This separation enables secure login while maintaining granular repo permissions through GitHub App installations.
When to Use
- Setting up GitHub OAuth login via Nango
- Implementing GitHub App installation webhooks
- Reconciling OAuth users with GitHub App installations
- Building apps that need both user auth and repo access
- Handling Nango sync webhooks for GitHub data
Why Two Connections?
GitHub has two different authentication mechanisms that serve different purposes:
GitHub OAuth App (github integration)
- What it is: Traditional OAuth for user identity
- What it gives you: User profile (name, email, avatar, GitHub ID)
- What it DOESN'T give you: Access to repositories
- Use for: Login, "Sign in with GitHub"
GitHub App (github-app-oauth integration)
- What it is: Installable app with granular repo permissions
- What it gives you: Access to specific repos the user installed it on
- What it DOESN'T give you: User identity (it knows the installation, not who's using it)
- Use for: Reading PRs, commits, files; posting comments; webhooks
The Reconciliation Problem
OAuth App alone: "User john@example.com logged in" → but which repos can they access?
GitHub App alone: "Installation #12345 has access to repo X" → but who is the user?
Solution: Two separate OAuth flows linked by user ID:
- Login flow → User authenticates → Store user identity +
nangoConnectionId - Repo flow → Same user authorizes app → Store repos + link via
ownerId
This lets you answer: "User john@example.com can access repos X, Y, Z"
Quick Reference
| Connection Type | Nango Integration | Purpose | Stored In |
|---|---|---|---|
| User Login | github |
Authentication, identity | users.nangoConnectionId |
| Repo Access | github-app-oauth |
PR operations, file access | repos.nangoConnectionId |
| Flow | Endpoint | Webhook Type |
|---|---|---|
| Login | GET /auth/nango-session |
auth + github |
| Repo Connect | GET /auth/github-app-session |
auth + github-app-oauth |
| Data Sync | N/A (scheduled) | sync |
Implementation
1. Database Schema
// users table - stores login connection
export const users = pgTable('users', {
id: uuid('id').primaryKey().defaultRandom(),
githubId: text('github_id').unique().notNull(),
githubUsername: text('github_username').notNull(),
email: text('email'),
avatarUrl: text('avatar_url'),
nangoConnectionId: text('nango_connection_id'), // Permanent login connection
incomingConnectionId: text('incoming_connection_id'), // Temp polling connection
pendingInstallationRequest: timestamp('pending_installation_request'), // Org approval wait
});
// repos table - stores per-repo app connection
export const repos = pgTable('repos', {
id: uuid('id').primaryKey().defaultRandom(),
githubRepoId: text('github_repo_id').unique().notNull(),
fullName: text('full_name').notNull(),
installationId: uuid('installation_id').references(() => githubInstallations.id),
ownerId: uuid('owner_id').references(() => users.id),
nangoConnectionId: text('nango_connection_id'), // App connection for this repo
});
// github_installations - tracks app installations
export const githubInstallations = pgTable('github_installations', {
id: uuid('id').primaryKey().defaultRandom(),
installationId: text('installation_id').unique().notNull(),
accountType: text('account_type'), // 'user' | 'organization'
accountLogin: text('account_login'),
installedById: uuid('installed_by_id').references(() => users.id),
});
2. Constants
// constants.ts
export const NANGO_INTEGRATION = {
GITHUB_USER: 'github', // Login only
GITHUB_APP_OAUTH: 'github-app-oauth', // Repo access
} as const;
3. Login Flow Routes
// GET /auth/nango-session - Create login OAuth session
app.get('/auth/nango-session', async (c) => {
const tempUserId = randomUUID();
const { sessionToken } = await nangoClient.createConnectSession({
end_user: { id: tempUserId },
allowed_integrations: [NANGO_INTEGRATION.GITHUB_USER],
});
return c.json({ sessionToken, tempUserId });
});
// GET /auth/nango/status/:connectionId - Poll login completion
app.get('/auth/nango/status/:connectionId', async (c) => {
const { connectionId } = c.req.param();
// Check if user exists with this incoming connection
const user = await userRepo.findByIncomingConnectionId(connectionId);
if (!user) {
return c.json({ ready: false });
}
// Issue JWT and return
const token = authService.issueToken(user);
await userRepo.clearIncomingConnectionId(user.id);
return c.json({ ready: true, token, user });
});
4. App OAuth Flow Routes
// GET /auth/github-app-session - Create app OAuth session (authenticated)
app.get('/auth/github-app-session', authMiddleware, async (c) => {
const user = c.get('user');
const { sessionToken } = await nangoClient.createConnectSession({
end_user: { id: user.id, email: user.email },
allowed_integrations: [NANGO_INTEGRATION.GITHUB_APP_OAUTH],
});
return c.json({ sessionToken });
});
// GET /auth/github-app/status/:connectionId - Poll repo sync
app.get('/auth/github-app/status/:connectionId', authMiddleware, async (c) => {
const user = c.get('user');
// Check for pending org approval
if (user.pendingInstallationRequest) {
return c.json({ ready: false, pendingApproval: true });
}
// Check if repos synced
const repos = await repoRepo.findByOwnerId(user.id);
return c.json({ ready: repos.length > 0, repos });
});
5. Auth Webhook Handler
// auth-webhook-service.ts
export async function handleAuthWebhook(payload: NangoAuthWebhook): Promise<boolean> {
const { connectionId, providerConfigKey, endUser } = payload;
if (providerConfigKey === NANGO_INTEGRATION.GITHUB_USER) {
return handleLoginWebhook(connectionId, endUser);
}
if (providerConfigKey === NANGO_INTEGRATION.GITHUB_APP_OAUTH) {
return handleAppOAuthWebhook(connectionId, endUser);
}
return false;
}
async function handleLoginWebhook(connectionId: string, endUser?: EndUser) {
// Fetch GitHub user info via Nango
const githubUser = await nangoService.getGitHubUser(connectionId);
// Check if user exists
const existingUser = await userRepo.findByGitHubId(String(githubUser.id));
if (existingUser) {
// Returning user - store temp connection for polling
await userRepo.update(existingUser.id, {
incomingConnectionId: connectionId,
});
// Delete duplicate connection later
await nangoService.deleteConnection(connectionId);
} else {
// New user - create record
const user = await userRepo.create({
githubId: String(githubUser.id),
githubUsername: githubUser.login,
email: githubUser.email,
avatarUrl: githubUser.avatar_url,
nangoConnectionId: connectionId,
incomingConnectionId: connectionId,
});
// Update connection with real user ID
await nangoService.patchConnection(connectionId, {
end_user: { id: user.id, email: user.email },
});
}
return true;
}
async function handleAppOAuthWebhook(connectionId: string, endUser?: EndUser) {
const userId = endUser?.id;
if (!userId) throw new Error('No user ID in app OAuth webhook');
const user = await userRepo.findById(userId);
if (!user) throw new Error('User not found');
try {
// Fetch repos user has access to
const repos = await githubService.getInstallationReposRaw(connectionId);
// Sync repos to database
for (const repo of repos) {
await repoRepo.upsert({
githubRepoId: String(repo.id),
fullName: repo.full_name,
ownerId: user.id,
nangoConnectionId: connectionId,
});
}
// Trigger Nango syncs
await nangoService.triggerSync(connectionId, ['pull-requests', 'commits']);
} catch (error) {
if (error.status === 403) {
// Org approval pending
await userRepo.update(user.id, {
pendingInstallationRequest: new Date(),
});
return true; // Graceful degradation
}
throw error;
}
return true;
}
6. Webhook Route with Signature Verification
// webhooks.ts
app.post('/api/webhooks/nango', async (c) => {
const signature = c.req.header('X-Nango-Signature');
const body = await c.req.text();
// Verify signature
const expectedSignature = createHmac('sha256', NANGO_SECRET_KEY).update(body).digest('hex');
if (signature !== expectedSignature) {
return c.json({ error: 'Invalid signature' }, 401);
}
const payload = JSON.parse(body);
if (payload.type === 'auth') {
const success = await handleAuthWebhook(payload);
return c.json({ success });
}
if (payload.type === 'sync') {
await processSyncWebhook(payload);
return c.json({ success: true });
}
return c.json({ success: false });
});
7. Frontend Integration
// Login flow
async function handleLogin() {
const res = await fetch('/api/auth/nango-session');
const { sessionToken } = await res.json();
const nango = new Nango({ connectSessionToken: sessionToken });
nango.openConnectUI({
onEvent: async (event) => {
if (event.type === 'connect') {
// Poll for completion
const result = await pollForAuth(event.payload.connectionId);
if (result.ready) {
localStorage.setItem('token', result.token);
navigate('/dashboard');
}
}
},
});
}
// Repo connection flow (after login)
async function handleConnectRepos() {
const res = await fetch('/api/auth/github-app-session', {
headers: { Authorization: `Bearer ${token}` },
});
const { sessionToken } = await res.json();
const nango = new Nango({ connectSessionToken: sessionToken });
nango.openConnectUI({
onEvent: async (event) => {
if (event.type === 'connect') {
const result = await pollForRepos(event.payload.connectionId);
if (result.pendingApproval) {
showMessage('Waiting for org admin approval...');
} else if (result.ready) {
setRepos(result.repos);
}
}
},
});
}
Complete Flow Diagram
USER LOGIN:
Frontend → GET /auth/nango-session
→ Nango.openConnectUI(sessionToken)
→ User authorizes GitHub
→ Nango webhook (type: auth, providerConfigKey: github)
→ Backend creates/updates user
→ Frontend polls /auth/nango/status/:connectionId
→ Returns JWT token
REPO CONNECTION (authenticated):
Frontend → GET /auth/github-app-session (with JWT)
→ Nango.openConnectUI(sessionToken)
→ User authorizes GitHub App
→ Nango webhook (type: auth, providerConfigKey: github-app-oauth)
→ Backend fetches repos, syncs to DB
→ Frontend polls /auth/github-app/status/:connectionId
→ Returns repos list
DATA SYNCS (background):
Nango → Scheduled sync every 4 hours
→ Webhook (type: sync, model: GithubPullRequest)
→ Backend processes incremental updates
Common Mistakes
| Mistake | Fix |
|---|---|
| Using same connection for login and repo access | Use two integrations: github for login, github-app-oauth for repos |
| Not handling org approval pending | Check for 403 error, set pendingInstallationRequest flag |
Missing endUser.id in connection |
Always set in createConnectSession, update after user creation |
| Polling wrong connection ID | Store incomingConnectionId separately for returning users |
| Not verifying webhook signature | Always verify X-Nango-Signature with HMAC-SHA256 |
| Keeping duplicate connections | Delete temp connection after returning user authenticates |
Environment Variables
# Required
NANGO_SECRET_KEY=your-nango-secret-key
JWT_SECRET=your-jwt-secret-min-32-chars
DATABASE_URL=postgres://...
# Configure in Nango Dashboard
# - github integration: OAuth App credentials
# - github-app-oauth integration: GitHub App credentials
Nango Dashboard Setup
-
Create
githubintegration (for login):- Type: OAuth2
- Client ID/Secret: From GitHub OAuth App
- Scopes:
read:user,user:email
-
Create
github-app-oauthintegration (for repos):- Type: GitHub App
- App ID, Private Key, Client ID/Secret: From GitHub App
- Scopes:
repo,pull_request, etc.
-
Configure webhook URL:
https://your-domain/api/webhooks/nango -
Enable syncs:
pull-requests,commits,issues, etc.
이 스킬의 파일
1github-oauth-nango-integration skill 질문
Claude Code에 github-oauth-nango-integration skill을 어떻게 설치하나요?
npx degit AgentWorkforce/relay/.claude/skills/github-oauth-nango-integration ~/.claude/skills/github-oauth-nango-integration를 실행합니다. Claude Code는 ~/.claude/skills(모든 프로젝트) 또는 .claude/skills(한 프로젝트)에서 skills를 로드하며, 설명이 작업과 일치할 때 skill을 사용합니다.
github-oauth-nango-integration skill을 사용할 수 있는 클라이언트는 무엇인가요?
Agent Skills 형식을 읽는 모든 클라이언트(Claude Code, Codex, Gemini CLI, claude.ai(ZIP으로 업로드))가 사용할 수 있습니다. skill 내 스크립트는 클라이언트가 코드 실행을 허용하는 경우에만 실행됩니다.
조직에서 GitHub App 설치 승인이 필요한 경우는 어떻게 처리하나요?
OAuth 흐름 중에 GitHub App이 403 에러를 반환하면, 이를 포착하여 해당 사용자의 설치 요청이 대기 중임을 표시할 수 있습니다.