Update Octokit to v5

[wrslatz]

Is your feature request related to a problem?

Update Octokit to v5. The current version is outdated, which may lead to unpatched bugs and vulnerabilities.

Describe the solution you'd like

Octokit v4 migrates to ESM, which is a breaking change. The repo will need to be migrated to ESM (or upgraded to a Node.js version that supports ESM in CJS, which may have compatibility issues for consumers that package the app themselves). Migration to ESM should likely be its own issue.

Describe alternatives you've considered

None. We eventually need to upgrade.

Detailed migration plan

Migration Plan

Executive Summary

This plan outlines a multi-phase migration from octokit@3.2.2 to octokit@5.x for the private-mirrors repository, including Probot v14 migration:

• Phase A: Migrate to octokit@4.x + probot@14.x
• Phase B: Migrate to octokit@5.x (latest: 5.0.5)

This incremental approach allows for easier debugging and rollback if issues arise.

Probot v14 Breaking Changes Summary

• ESM-only package
• Requires Node.js 20.18+ or 22+
• Webhook types moved from @octokit/webhooks-types to @octokit/openapi-webhooks-types-migration
• Legacy REST endpoints removed (must use octokit.rest.*)
• Express server removed from Probot
• createNodeMiddleware() is now async
• HTTP server listens on localhost by default (not 0.0.0.0)

Current State

Direct Octokit Dependencies (package.json)

• octokit: 3.2.2
• @octokit/auth-app: 6.1.1
• @octokit/graphql-schema: 15.26.0

Related Dependencies

• probot: 13.4.7 (uses @octokit/core@^5.2.2, @octokit/types@^12.3.0)
• github-app-webhook-relay-polling: 2.0.0 (devDependency, uses @octokit/app@^15.1.0)
• @probot/octokit-plugin-config: 2.0.1 (peer dep: @octokit/core>=5)

Files Using Octokit (21 files total)

Core Octokit Configuration:

• src/bot/rest.ts - Custom Octokit class with plugin
• src/bot/octokit.ts - App/installation/personal Octokit factories

Server Layer:

• src/server/repos/controller.ts - Repository CRUD operations
• src/server/git/controller.ts - Git ref operations
• src/server/octokit/controller.ts - App installation checking

Authentication:

• src/app/api/auth/lib/nextauth-options.ts - NextAuth with personal Octokit
• src/utils/auth.ts - GitHub auth utilities

Bot/Webhooks:

• src/bot/index.ts - Probot webhook handlers
• src/bot/config.ts - Config fetching
• src/bot/rules.ts - Branch protection (REST, GraphQL, Rulesets)

Frontend Hooks:

• src/hooks/useForks.tsx - GraphQL pagination
• src/hooks/useOrganization.tsx
• src/hooks/useOrganizations.tsx
• src/hooks/useFork.tsx

Tests:

• test/octomock/index.ts - Octokit mock implementation
• Various test files

---

Octokit v4 Breaking Changes

1. ESM-Only Package

• Octokit v4 is ESM-only (no more CommonJS support)
• The project already uses ESM ("type": "module" implied by Next.js setup)
• Impact: Minimal - project already configured for ESM

1. Node.js Version Requirement

• Octokit v4 requires Node.js 18+
• Current package.json engines: "node": "^20.9 || ^22"
• Impact: None - already compatible

1. Updated @octokit/* Dependencies

Octokit v4 updates internal dependencies:

• @octokit/core: 5.x → 6.x
• @octokit/types: 12.x/13.x → 14.x
• @octokit/auth-app: 6.x → 7.x
• @octokit/plugin-paginate-rest: removes CJS variants
• @octokit/plugin-rest-endpoint-methods: removes CJS variants

1. @octokit/auth-app Changes (6.x → 7.x)

• Updated type exports
• Uses @octokit/types@14.x
• createAppAuth function signature unchanged

1. Plugin API Changes

• Plugin registration unchanged (.plugin() method)
• Type inference improvements

1. RequestError Import

• Now exported directly from octokit package
• import { RequestError } from "octokit" (already available in v3)

---

Dependencies to Update

Required Updates

Package	Current	Target	Notes
octokit	3.2.2	4.x	Main package
@octokit/auth-app	6.1.1	7.x	Must match octokit v4 peer requirements
@octokit/graphql-schema	15.26.0	Latest	Update for new GraphQL types

Dependency Compatibility Check

Package	Compatibility with Octokit v4
probot@13.4.7	NEEDS INVESTIGATION - Uses @octokit/core@^5.2.2. May need update or may be compatible via peer deps
@probot/octokit-plugin-config@2.0.1	Peer dep is @octokit/core>=5 - Should work with v6
github-app-webhook-relay-polling@2.0.0	DevDependency only, uses @octokit/app@^15.1.0 - May have conflicts

Potential Probot Compatibility Issue

Critical: Probot 13.x explicitly depends on @octokit/core@^5.2.2. Octokit v4 uses @octokit/core@6.x.

Options:

1. Check if Probot 14.x exists with @octokit/core@6 support
2. If no Probot update available, may need to:

• Keep octokit v3 OR
• Use npm overrides/resolutions to force compatible versions
• Accept dual @octokit/core versions in node_modules (may work)

---

Code Changes Required

1. src/bot/rest.ts (lines 1-8)

   // Current
   import { config } from '@probot/octokit-plugin-config'
   import { Octokit as Core } from 'octokit'
   
   export const Octokit = Core.plugin(config).defaults({
     userAgent: `octokit-rest.js/repo-sync-bot`,
   })

   Change: No code changes expected - plugin API unchanged

2. src/bot/octokit.ts

   // Current
   import { createAppAuth } from '@octokit/auth-app'

   Change: No code changes expected - createAppAuth API unchanged in v7

3. src/bot/rules.ts (line 1)

   // Current
   import { Repository } from '@octokit/graphql-schema'

   Change: May need type name updates if schema changed

4. src/bot/config.ts (line 1)

   // Current
   import { Configuration } from '@probot/octokit-plugin-config/dist-types/types'

   Change: Verify import path still valid after plugin update

5. Type Updates Throughout

   • @octokit/types v14.x may have renamed or modified types
   • Review all files importing from @octokit/* packages
   • Update any broken type references

6. Test Mocks (test/octomock/index.ts)

   • Update mock implementations if API method signatures changed
   • Verify all mocked methods still exist

---

Migration Steps

Phase 1: Dependency Analysis

1. Check npm for latest Probot version and its @octokit/core peer dependency
2. Verify @probot/octokit-plugin-config compatibility with @octokit/core@6
3. Check github-app-webhook-relay-polling compatibility

Phase 2: Update Dependencies

1. Update package.json:

   {
     "dependencies": {
       "octokit": "^4.0.0",
       "@octokit/auth-app": "^7.0.0",
       "@octokit/graphql-schema": "^15.26.0"
     }
   }

2. Run npm install and check for peer dependency warnings

3. If Probot conflicts exist, add resolutions/overrides as needed

Phase 3: Code Updates

1. Fix any TypeScript compilation errors from type changes
2. Update imports if any package export paths changed
3. Update test mocks as needed

Phase 4: Testing

1. Run npm run lint - fix any new lint errors
2. Run npm test - ensure all tests pass
3. Run npm run build - verify production build succeeds
4. Manual testing of GitHub API operations

Phase 5: Validation

1. Test GitHub App authentication flow
2. Test installation Octokit operations
3. Test personal Octokit operations
4. Test GraphQL queries and pagination
5. Test branch protection creation (all 3 methods)
6. Test webhook handling via Probot

---

Risk Assessment

Risk	Likelihood	Impact	Mitigation
Probot incompatibility	Medium	High	Check for Probot updates first; consider npm overrides
Type breaking changes	Low	Medium	TypeScript will catch at compile time
Runtime API changes	Low	High	Comprehensive test coverage exists
Plugin compatibility	Low	Low	@probot/octokit-plugin-config uses generic peer deps

---

Rollback Plan

1. Keep the current package-lock.json backed up
2. If issues arise, revert package.json changes and restore lock file
3. All changes are isolated to dependency versions - no architectural changes

---

Files to Modify

File	Changes
package.json	Update octokit, @octokit/auth-app, probot versions; update engines
src/pages/api/webhooks.ts	CRITICAL: Update for async createNodeMiddleware()
src/bot/rest.ts	Verify plugin compatibility
src/bot/rules.ts	Update type imports if needed
src/bot/config.ts	Verify plugin import path
src/bot/index.ts	Verify webhook handlers (likely no changes needed)
test/octomock/index.ts	Update mocks if API changed

---

PHASE A: Migrate to Octokit v4 + Probot v14

Step A1: Update Dependencies for v4 + Probot v14

Update package.json:

{
    "dependencies": {
        "octokit": "^4.1.4",
        "@octokit/auth-app": "^7.0.0",
        "@octokit/graphql-schema": "^15.26.0",
        "probot": "^14.0.0"
    },
    "devDependencies": {
        "@octokit/openapi-webhooks-types-migration": "^x.x.x"
    },
    "engines": {
        "node": "^20.18 || ^22"
    }
}

Step A2: Update Probot Webhook Handlers

File: src/bot/index.ts

Probot v14 removes legacy endpoint methods - must use context.octokit.rest.\*:

// Before (if using legacy pattern)
// context.octokit.repos.updateBranchProtection(...)

// After (already correct in this codebase)
context.octokit.rest.repos.updateBranchProtection(...)

Note: This codebase already uses context.octokit.rest.\* pattern (confirmed in src/bot/rules.ts:244), so minimal changes expected.

Step A3: Update Webhook Type Imports (if any)

If any files import from @octokit/webhooks-types:
No @octokit/webhooks-types imports found in codebase - no changes needed.

Step A4: Handle createNodeMiddleware() Async Change

File: src/pages/api/webhooks.ts

createNodeMiddleware() is now async in Probot v14. This file must be updated:

// Current (lines 15-25)
export default createNodeMiddleware(app, {
probot: createProbot({
defaults: {
log: {
child: () => probotLogger,
} as any,
},
}),
webhooksPath: '/api/webhooks',
})

// Updated for Probot v14 (Next.js API route with async export)
// Option 1: Dynamic import pattern
let middleware: ReturnType<typeof createNodeMiddleware> | null = null

const getMiddleware = async () => {
if (!middleware) {
middleware = await createNodeMiddleware(app, {
probot: createProbot({
defaults: {
log: {
child: () => probotLogger,
} as any,
},
}),
webhooksPath: '/api/webhooks',
})
}
return middleware
}

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
const mw = await getMiddleware()
return mw(req, res)
}

Note: Next.js API routes can export async default functions, so this should work. Alternatively, could initialize at module level with top-level await if using ESM.

Step A5: Run Install and Fix Peer Dependencies

npm install

• Address any peer dependency warnings

Step A6: Fix Type Errors

• Run npm run build to identify TypeScript errors
• Fix any type import changes

Step A7: Test

• Run npm run lint
• Run npm test
• Run npm run build

Step A8: Commit v4 + Probot v14 Migration

• Commit working v4 + Probot v14 migration as checkpoint

---

PHASE B: Migrate to Octokit v5

Octokit v5 Breaking Changes (v4 → v5)

Based on semantic versioning, v5.0.0 introduces breaking changes:

1. @octokit/core 6.x: Now uses @octokit/core v6 (if not already in v4)
2. Type refinements: Further TypeScript type updates
3. Plugin compatibility: Ensure all plugins support v5

Step B1: Update Dependencies for v5

Update package.json:

{
  "dependencies": {
    "octokit": "^5.0.5",
    "@octokit/auth-app": "^7.x.x",
    "@octokit/graphql-schema": "latest"
  }
}

Step B2: Run Install and Fix Peer Dependencies

• Run npm install

Step B3: Fix Type Errors

• Run npm run build to identify TypeScript errors
• Fix any type import changes from v4 to v5

Step B4: Test

• Run npm run lint
• Run npm test
• Run npm run build

Step B5: Final Validation

1. Test GitHub App authentication flow
2. Test installation Octokit operations
3. Test personal Octokit operations
4. Test GraphQL queries and pagination
5. Test branch protection creation (all 3 methods)
6. Test webhook handling via Probot

Step B6: Commit v5 Migration

• Final commit with v5 migration complete

---

Summary of Migration Steps

1. Phase A: Update to octokit@4.1.4 + probot@14.0.0
   • Update dependencies in package.json
   • Update Node.js engine requirement to ^20.18 || ^22
   • Verify webhook handlers use context.octokit.rest.* pattern
   • Update any @octokit/webhooks-types imports if present
   • Fix type errors, test, commit
2. Phase B: Update to octokit@5.0.5
   • Update octokit to latest
   • Fix any additional type errors
   • Test, commit
3. Validation: Manual testing of GitHub App functionality

[wrslatz]

@riley-kohler FYI #402 seems to be related to the override from #330 and breaking dependabot updates now. We may want to prioritize this and the other dependency updates to resolve this fully.