Summary

Adds createOctokit(token) to the script execution context alongside github, context, core, etc. It returns a new Octokit client using the same default configuration as the pre-built github client — retry, request logging, orchestration ID, base URL handling, user-agent, and the action's retries input. Callers can optionally override options and plugins.

createOctokit(token: string, options?: OctokitOptions, ...plugins: OctokitPlugin[]): InstanceType<typeof GitHub>

This is a new addition — the existing github client and all other context variables are unchanged.

Motivation

Workflows commonly need multiple authentication tokens — for example, a GITHUB_TOKEN for the current repo and a separate PAT or GitHub App installation token for cross-repo operations. Today the only way to create additional Octokit clients in github-script is through require('@actions/github'), which:

1. Is an undocumented implementation detail
2. Returns a bare client — no retry plugin, no request logging, no orchestration ID tracking
3. Can break if the bundling strategy changes

createOctokit(token) gives users a supported, first-class way to create additional clients that inherit the action's configuration.

Why the name is createOctokit

createOctokit is named intentionally. github-script injects context values as function parameters (new AsyncFunction(...Object.keys(args), source)), so exposing getOctokit directly would collide with scripts that already do:

const { getOctokit } = require('@actions/github')

This throws SyntaxError: Identifier 'getOctokit' has already been declared — const/let cannot redeclare a function parameter. This pattern appears in ~10 public workflows today (e.g. MetaMask, github/migration-actions). createOctokit avoids the collision and better communicates factory semantics — each call creates a new client instance.

Demo: 8-job before/after workflow run — BEFORE jobs use getOctokit binding and hit SyntaxError; AFTER jobs use createOctokit and pass cleanly.

What createOctokit inherits

createOctokit uses the same default configuration as the built-in github client: base URL handling (GHES / Proxima / base-url input), user-agent with orchestration ID, previews, debug logger, @octokit/plugin-retry, @octokit/plugin-request-log, and the action's retries count — unless explicitly overridden.

Overrides are merged, not replaced: partial request or retry options (e.g. {request: {timeout: 5000}}) are deep-merged with inherited defaults so they don't clobber unrelated fields. undefined values in user options are stripped to prevent accidental clobbering (e.g. {baseUrl: undefined} wiping a GHES URL). Default plugins are always included; user-supplied duplicates are skipped.

Usage

- uses: actions/github-script@v8
  env:
    APP_TOKEN: ${{ secrets.APP_INSTALLATION_TOKEN }}
  with:
    script: |
      // Default client using github-token input
      const { data: issue } = await github.rest.issues.get({
        owner: context.repo.owner,
        repo: context.repo.repo,
        issue_number: context.issue.number
      })

      // Second client using a different token
      const app = createOctokit(process.env.APP_TOKEN)
      await app.rest.repos.createDispatchEvent({
        owner: 'my-org',
        repo: 'another-repo',
        event_type: 'trigger-deploy',
        client_payload: { issue: issue.number }
      })

Changes

• src/create-configured-getoctokit.ts (new) — Factory wrapper around @actions/github's getOctokit with deep-merge, stripUndefined, and plugin deduplication
• src/main.ts — Creates the wrapped factory and adds createOctokit to the script context
• src/async-function.ts / types/async-function.d.ts — Added createOctokit to AsyncFunctionArguments type
• .github/workflows/integration.yml — Added test-get-octokit integration job
• README.md — Documents createOctokit in the context variables table
• dist/index.js — Rebuilt

Tests

• __test__/create-configured-getoctokit.test.ts — 15 tests: option merging, stripUndefined, retry deep-merge, plugin dedup, no-mutation, falsy-but-valid values (0, false, '')
• __test__/async-function.test.ts — 9 tests: verifies createOctokit is passed through to scripts
• __test__/getoctokit-integration.test.ts — 4 integration tests for multi-token usage

Checklist

• createOctokit added to script execution context
• TypeScript types updated
• README.md documents createOctokit
• dist/ rebuilt
• Unit tests (15 factory + 9 async function)
• Integration tests (4 multi-token + CI workflow job)
• No breaking changes — createOctokit is a new binding; existing scripts unaffected