actions/github-script
1
0
Fork 0
mirror of https://github.com/actions/github-script.git synced 2026-05-13 03:16:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README examples from @v8 to @v9, add getOctokit docs and v9 breaking changes

Browse Source
This commit is contained in:
Salman Muin Kayser Chishti
2026-04-09 18:14:24 +00:00
committed by Salman Muin Kayser Chishti
parent c17d55b90d
commit 3953caf885
1 changed files with 126 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

153
README.md
View File

@@ -38,6 +38,7 @@ The following arguments will be provided:
- `glob` A reference to the [@actions/glob](https://github.com/actions/toolkit/tree/main/packages/glob) package
- `io` A reference to the [@actions/io](https://github.com/actions/toolkit/tree/main/packages/io) package
- `exec` A reference to the [@actions/exec](https://github.com/actions/toolkit/tree/main/packages/exec) package
- `getOctokit` A factory function to create additional authenticated Octokit clients with different tokens (see [Creating additional clients](#creating-additional-clients-with-getoctokit))
- `require` A proxy wrapper around the normal Node.js `require` to enable
requiring relative paths (relative to the current working directory) and
requiring npm packages installed in the current working directory. If for
@@ -53,6 +54,21 @@ documentation.
## Breaking Changes
### V9
Version 9 of this action upgrades to `@actions/github` v9, which brings the latest Octokit types and features.
**New features:**
- **`getOctokit` factory function** — Available directly in the script context. Create additional authenticated Octokit clients with different tokens for multi-token workflows, GitHub App tokens, and cross-org access. See [Creating additional clients with `getOctokit`](#creating-additional-clients-with-getoctokit) for details and examples.
- **Orchestration ID in user-agent** — The `ACTIONS_ORCHESTRATION_ID` environment variable is automatically appended to the user-agent string for request tracing.
**Breaking changes:**
- **`require('@actions/github')` no longer works in scripts.** The upgrade to `@actions/github` v9 (ESM-only) means `require('@actions/github')` will fail at runtime. If you previously used patterns like `const { getOctokit } = require('@actions/github')` to create secondary clients, use the new injected `getOctokit` function instead — it's available directly in the script context with no imports needed.
- `getOctokit` is now an injected function parameter. Scripts that declare `const getOctokit = ...` or `let getOctokit = ...` will get a `SyntaxError` because JavaScript does not allow `const`/`let` redeclaration of function parameters. Use the injected `getOctokit` directly, or use `var getOctokit = ...` if you need to redeclare it.
- If your script accesses other `@actions/github` internals beyond the standard `github`/`octokit` client, you may need to update those references for v9 compatibility.
### V8
Version 8 of this action updated the runtime to Node 24 - https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions
@@ -90,16 +106,16 @@ See [development.md](/docs/development.md).
## Passing inputs to the script
Actions expressions are evaluated before the `script` is passed to the action, so the result of any expressions
*will be evaluated as JavaScript code*.
_will be evaluated as JavaScript code_.
It's highly recommended to *not* evaluate expressions directly in the `script` to avoid
It's highly recommended to _not_ evaluate expressions directly in the `script` to avoid
[script injections](https://docs.github.com/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections)
and potential `SyntaxError`s when the expression is not valid JavaScript code (particularly when it comes to improperly escaped strings).
To pass inputs, set `env` vars on the action step and reference them in your script with `process.env`:
```yaml
- uses: actions/github-script@v8
- uses: actions/github-script@v9
env:
TITLE: ${{ github.event.pull_request.title }}
with:
@@ -118,7 +134,7 @@ The return value of the script will be in the step's outputs under the
"result" key.
```yaml
- uses: actions/github-script@v8
- uses: actions/github-script@v9
id: set-result
with:
script: return "Hello!"
@@ -137,7 +153,7 @@ output of a github-script step. For some workflows, string encoding is preferred
`result-encoding` input:
```yaml
- uses: actions/github-script@v8
- uses: actions/github-script@v9
id: my-script
with:
result-encoding: string
@@ -149,7 +165,7 @@ output of a github-script step. For some workflows, string encoding is preferred
By default, requests made with the `github` instance will not be retried. You can configure this with the `retries` option:
```yaml
- uses: actions/github-script@v8
- uses: actions/github-script@v9
id: my-script
with:
result-encoding: string
@@ -167,7 +183,7 @@ In this example, request failures from `github.rest.issues.get()` will be retrie
You can also configure which status codes should be exempt from retries via the `retry-exempt-status-codes` option:
```yaml
- uses: actions/github-script@v8
- uses: actions/github-script@v9
id: my-script
with:
result-encoding: string
@@ -196,7 +212,7 @@ By default, github-script will use the token provided to your workflow.
```yaml
- name: View context attributes
uses: actions/github-script@v8
uses: actions/github-script@v9
with:
script: console.log(context)
```
@@ -212,7 +228,7 @@ jobs:
comment:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v8
- uses: actions/github-script@v9
with:
script: |
github.rest.issues.createComment({
@@ -234,7 +250,7 @@ jobs:
apply-label:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v8
- uses: actions/github-script@v9
with:
script: |
github.rest.issues.addLabels({
@@ -256,7 +272,7 @@ jobs:
welcome:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v8
- uses: actions/github-script@v9
with:
script: |
// Get a list of all issues created by the PR opener
@@ -301,7 +317,7 @@ jobs:
diff:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v8
- uses: actions/github-script@v9
with:
script: |
const diff_url = context.payload.pull_request.diff_url
@@ -325,7 +341,7 @@ jobs:
list-issues:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v8
- uses: actions/github-script@v9
with:
script: |
const query = `query($owner:String!, $name:String!, $label:String!) {
@@ -359,7 +375,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/github-script@v8
- uses: actions/github-script@v9
with:
script: |
const script = require('./path/to/script.js')
@@ -397,7 +413,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/github-script@v8
- uses: actions/github-script@v9
env:
SHA: '${{env.parentSHA}}'
with:
@@ -441,7 +457,7 @@ jobs:
- run: npm ci
# or one-off:
- run: npm install execa
- uses: actions/github-script@v8
- uses: actions/github-script@v9
with:
script: |
const execa = require('execa')
@@ -471,7 +487,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/github-script@v8
- uses: actions/github-script@v9
with:
script: |
const { default: printStuff } = await import('${{ github.workspace }}/src/print-stuff.js')
@@ -483,21 +499,22 @@ jobs:
If you want type support for your scripts, you could use the command below to install the
`@actions/github-script` type declaration.
```sh
$ npm i -D @actions/github-script@github:actions/github-script
```
And then add the `jsDoc` declaration to your script like this:
```js
// @ts-check
/** @param {import('@actions/github-script').AsyncFunctionArguments} AsyncFunctionArguments */
export default async ({ core, context }) => {
core.debug("Running something at the moment");
return context.actor;
};
export default async ({core, context}) => {
core.debug('Running something at the moment')
return context.actor
}
```
### Using a separate GitHub token
The `GITHUB_TOKEN` used by default is scoped to the current repository, see [Authentication in a workflow](https://docs.github.com/actions/reference/authentication-in-a-workflow).
@@ -506,25 +523,89 @@ If you need access to a different repository or an API that the `GITHUB_TOKEN` d
[Learn more about creating and using encrypted secrets](https://docs.github.com/actions/reference/encrypted-secrets)
```yaml
on:
issues:
types: [opened]
### Creating additional clients with `getOctokit`
jobs:
apply-label:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v8
The `getOctokit` function is available in the script context and lets you create additional authenticated Octokit clients — useful when you need to interact with the GitHub API using a different token than the one provided to the action (e.g. a GitHub App installation token, a PAT for cross-org access, or a fine-grained token with different permissions).
```js
getOctokit(token)
getOctokit(token, opts)
```
**Parameters:**
| Name | Type | Description |
| ------- | -------- | --------------------------------------------------------------------------------------- |
| `token` | `string` | **Required.** A GitHub token (PAT, GitHub App token, etc.) |
| `opts` | `object` | Optional. Octokit constructor options (e.g. `userAgent`, `baseUrl`, `request`, `retry`) |
The returned client is fully configured with the same plugins as `github` (retry, request-log, proxy support) — you don't need to set those up yourself.
**Option merging behavior:** `request` and `retry` are deep-merged with the action's defaults, so you can override individual fields (e.g. `{request: {timeout: 5000}}`) without losing the inherited retry count or proxy settings. All other top-level options (like `baseUrl` or `userAgent`) are replaced outright if you provide them.
> **Note:** `getOctokit` is injected as a function parameter (like `github`, `context`, `core`, etc.). You cannot redeclare it with `const` or `let` — this will cause a `SyntaxError`. Use `getOctokit` directly, or use `var` if you need to redeclare it. See [V9 breaking changes](#v9) for details.
#### Basic usage — one primary token, one secondary token
```yaml
- uses: actions/github-script@v9
env:
APP_TOKEN: ${{ secrets.MY_APP_TOKEN }}
with:
github-token: ${{ secrets.MY_PAT }}
github-token: ${{ secrets.GITHUB_TOKEN }}
script: |
github.rest.issues.addLabels({
// `github` uses GITHUB_TOKEN (scoped to this repo)
await github.rest.issues.addLabels({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
labels: ['Triage']
labels: ['triage']
})
// `getOctokit` creates a second client with a different token
const appOctokit = getOctokit(process.env.APP_TOKEN)
await appOctokit.rest.repos.createDispatchEvent({
owner: 'my-org',
repo: 'another-repo',
event_type: 'trigger-deploy'
})
```
#### Multiple clients for cross-org workflows
```yaml
- uses: actions/github-script@v9
env:
ORG_A_TOKEN: ${{ secrets.ORG_A_PAT }}
ORG_B_TOKEN: ${{ secrets.ORG_B_PAT }}
with:
script: |
const orgA = getOctokit(process.env.ORG_A_TOKEN)
const orgB = getOctokit(process.env.ORG_B_TOKEN)
const [repoA, repoB] = await Promise.all([
orgA.rest.repos.get({ owner: 'org-a', repo: 'service' }),
orgB.rest.repos.get({ owner: 'org-b', repo: 'service' })
])
console.log(`Org A: ${repoA.data.full_name}`)
console.log(`Org B: ${repoB.data.full_name}`)
```
#### Custom options
```yaml
- uses: actions/github-script@v9
env:
GHES_TOKEN: ${{ secrets.GHES_PAT }}
with:
script: |
const ghes = getOctokit(process.env.GHES_TOKEN, {
baseUrl: 'https://github.example.com/api/v3'
})
const { data } = await ghes.rest.repos.listForOrg({ org: 'internal' })
console.log(`Found ${data.length} repos on GHES`)
```
### Using exec package
@@ -539,7 +620,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/github-script@v8
- uses: actions/github-script@v9
with:
script: |
const exitCode = await exec.exec('echo', ['hello'])
@@ -557,7 +638,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/github-script@v8
- uses: actions/github-script@v9
with:
script: |
const {