actions/github-script

This action makes it easy to quickly write a script in your workflow that uses the GitHub API and the workflow run context.

Note

Thank you for your interest in this GitHub action, however, right now we are not taking contributions.

We continue to focus our resources on strategic areas that help our customers be successful while making developers’ lives easier. While GitHub Actions remains a key part of this vision, we are allocating resources towards other areas of Actions and are not taking contributions to this repository at this time. The GitHub public roadmap is the best place to follow along for any updates on features we’re working on and what stage they’re in.

We are taking the following steps to better direct requests related to GitHub Actions, including:

1. We will be directing questions and support requests to our Community Discussions area

2. High Priority bugs can be reported through Community Discussions or you can report these to our support team https://support.github.com/contact/bug-report.

3. Security Issues should be handled as per our security.md

We will still provide security updates for this project and fix major breaking changes during this time.

You are welcome to still raise bugs in this repo.

This action

To use this action, provide an input named script that contains the body of an asynchronous JavaScript function call. The following arguments will be provided:

• github A pre-authenticated octokit/rest.js client with pagination plugins
• context An object containing the context of the workflow run
• core A reference to the @actions/core package
• glob A reference to the @actions/glob package
• io A reference to the @actions/io package
• exec A reference to the @actions/exec package
• getOctokit A factory function to create additional authenticated Octokit clients with different tokens (see Creating additional clients)
• 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 some reason you need the non-wrapped require, there is an escape hatch available: __original_require__ is the original value of require without our wrapping applied.

Since the script is just a function body, these values will already be defined, so you don’t have to import them (see examples below).

See octokit/rest.js for the API client 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 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

All scripts are now run with Node 24 instead of Node 20 and are affected by any breaking changes between Node 20 and 24.

This requires a minimum Actions Runner version of v2.327.1

V7

Version 7 of this action updated the runtime to Node 20 - https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions

All scripts are now run with Node 20 instead of Node 16 and are affected by any breaking changes between Node 16 and 20

The previews input now only applies to GraphQL API calls as REST API previews are no longer necessary - https://github.blog/changelog/2021-10-14-rest-api-preview-promotions/.

V6

Version 6 of this action updated the runtime to Node 16 - https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions

All scripts are now run with Node 16 instead of Node 12 and are affected by any breaking changes between Node 12 and 16.

V5

Version 5 of this action includes the version 5 of @actions/github and @octokit/plugin-rest-endpoint-methods. As part of this update, the Octokit context available via github no longer has REST methods directly. These methods are available via github.rest.* - https://github.com/octokit/plugin-rest-endpoint-methods.js/releases/tag/v5.0.0

For example, github.issues.createComment in V4 becomes github.rest.issues.createComment in V5

github.request, github.paginate, and github.graphql are unchanged.

Development

See 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.

It’s highly recommended to not evaluate expressions directly in the script to avoid script injections and potential SyntaxErrors 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:

- uses: actions/github-script@v9
  env:
    TITLE: ${{ github.event.pull_request.title }}
  with:
    script: |
      const title = process.env.TITLE;
      if (title.startsWith('octocat')) {
        console.log("PR title starts with 'octocat'");
      } else {
        console.error("PR title did not start with 'octocat'");
      }

Reading step results

The return value of the script will be in the step’s outputs under the “result” key.

- uses: actions/github-script@v9
  id: set-result
  with:
    script: return "Hello!"
    result-encoding: string
- name: Get result
  run: echo "${{steps.set-result.outputs.result}}"

See “Result encoding” for details on how the encoding of these outputs can be changed.

Result encoding

By default, the JSON-encoded return value of the function is set as the “result” in the output of a github-script step. For some workflows, string encoding is preferred. This option can be set using the result-encoding input:

- uses: actions/github-script@v9
  id: my-script
  with:
    result-encoding: string
    script: return "I will be string (not JSON) encoded!"

Retries

By default, requests made with the github instance will not be retried. You can configure this with the retries option:

- uses: actions/github-script@v9
  id: my-script
  with:
    result-encoding: string
    retries: 3
    script: |
      github.rest.issues.get({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
      })

In this example, request failures from github.rest.issues.get() will be retried up to 3 times.

You can also configure which status codes should be exempt from retries via the retry-exempt-status-codes option:

- uses: actions/github-script@v9
  id: my-script
  with:
    result-encoding: string
    retries: 3
    retry-exempt-status-codes: 400,401
    script: |
      github.rest.issues.get({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
      })

By default, the following status codes will not be retried: 400, 401, 403, 404, 422 (source).

These retries are implemented using the octokit/plugin-retry.js plugin. The retries use exponential backoff to space out retries. (source)

Examples

Note that github-token is optional in this action, and the input is there in case you need to use a non-default token.

By default, github-script will use the token provided to your workflow.

Print the available attributes of context

- name: View context attributes
  uses: actions/github-script@v9
  with:
    script: console.log(context)

Comment on an issue

on:
  issues:
    types: [opened]

jobs:
  comment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v9
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '👋 Thanks for reporting!'
            })

Apply a label to an issue

on:
  issues:
    types: [opened]

jobs:
  apply-label:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v9
        with:
          script: |
            github.rest.issues.addLabels({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              labels: ['Triage']
            })

Welcome a first-time contributor

You can format text in comments using the same Markdown syntax as the GitHub web interface:

on: pull_request_target

jobs:
  welcome:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v9
        with:
          script: |
            // Get a list of all issues created by the PR opener
            // See: https://octokit.github.io/rest.js/#pagination
            const creator = context.payload.sender.login
            const opts = github.rest.issues.listForRepo.endpoint.merge({
              ...context.issue,
              creator,
              state: 'all'
            })
            const issues = await github.paginate(opts)

            for (const issue of issues) {
              if (issue.number === context.issue.number) {
                continue
              }

              if (issue.pull_request) {
                return // Creator is already a contributor.
              }
            }

            await github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `**Welcome**, new contributor!

                Please make sure you've read our [contributing guide](CONTRIBUTING.md) and we look forward to reviewing your Pull request shortly ✨`
            })

Download data from a URL

You can use the github object to access the Octokit API. For instance, github.request

on: pull_request

jobs:
  diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v9
        with:
          script: |
            const diff_url = context.payload.pull_request.diff_url
            const result = await github.request(diff_url)
            console.log(result)

(Note that this particular example only works for a public URL, where the diff URL is publicly accessible. Getting the diff for a private URL requires using the API.)

This will print the full diff object in the screen; result.data will contain the actual diff text.

Run custom GraphQL queries

You can use the github.graphql object to run custom GraphQL queries against the GitHub API.

jobs:
  list-issues:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v9
        with:
          script: |
            const query = `query($owner:String!, $name:String!, $label:String!) {
              repository(owner:$owner, name:$name){
                issues(first:100, labels: [$label]) {
                  nodes {
                    id
                  }
                }
              }
            }`;
            const variables = {
              owner: context.repo.owner,
              name: context.repo.repo,
              label: 'wontfix'
            }
            const result = await github.graphql(query, variables)
            console.log(result)

Run a separate file

If you don’t want to inline your entire script that you want to run, you can use a separate JavaScript module in your repository like so:

on: push

jobs:
  echo-input:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/github-script@v9
        with:
          script: |
            const script = require('./path/to/script.js')
            console.log(script({github, context}))

And then export a function from your module:

module.exports = ({github, context}) => {
  return context.payload.client_payload.value
}

Note that because you can’t require things like the GitHub context or Actions Toolkit libraries, you’ll want to pass them as arguments to your external function.

Additionally, you’ll want to use the checkout action to make sure your script file is available.

Run a separate file with an async function

You can also use async functions in this manner, as long as you await it in the inline script.

In your workflow:

on: push

jobs:
  echo-input:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/github-script@v9
        env:
          SHA: '${{env.parentSHA}}'
        with:
          script: |
            const script = require('./path/to/script.js')
            await script({github, context, core})

And then export an async function from your module:

module.exports = async ({github, context, core}) => {
  const {SHA} = process.env
  const commit = await github.rest.repos.getCommit({
    owner: context.repo.owner,
    repo: context.repo.repo,
    ref: `${SHA}`
  })
  core.exportVariable('author', commit.data.commit.author.email)
}

Use npm packages

Like importing your own files above, you can also use installed modules. Note that this is achieved with a wrapper on top require, so if you’re trying to require a module inside your own file, you might need to import it externally or pass the require wrapper to your file:

on: push

jobs:
  echo-input:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
      - run: npm ci
      # or one-off:
      - run: npm install execa
      - uses: actions/github-script@v9
        with:
          script: |
            const execa = require('execa')

            const { stdout } = await execa('echo', ['hello', 'world'])

            console.log(stdout)

Use ESM import

To import an ESM file, you’ll need to reference your script by an absolute path and ensure you have a package.json file with "type": "module" specified.

For a script in your repository src/print-stuff.js:

export default function printStuff() {
  console.log('stuff')
}

on: push

jobs:
  print-stuff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/github-script@v9
        with:
          script: |
            const { default: printStuff } = await import('${{ github.workspace }}/src/print-stuff.js')

            await printStuff()

Use scripts with jsDoc support

If you want type support for your scripts, you could use the command below to install the @actions/github-script type declaration.

$ npm i -D @actions/github-script@github:actions/github-script

And then add the jsDoc declaration to your script like this:

// @ts-check
/** @param {import('@actions/github-script').AsyncFunctionArguments} AsyncFunctionArguments */
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.

If you need access to a different repository or an API that the GITHUB_TOKEN doesn’t have permissions to, you can provide your own PAT as a secret using the github-token input.

Learn more about creating and using encrypted secrets

Creating additional clients with getOctokit

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).

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 for details.

Basic usage — one primary token, one secondary token

- uses: actions/github-script@v9
  env:
    APP_TOKEN: ${{ secrets.MY_APP_TOKEN }}
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    script: |
      // `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']
      })

      // `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

- 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

- 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

The provided @actions/exec package allows to execute command or tools in a cross platform way:

on: push

jobs:
  use-exec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/github-script@v9
        with:
          script: |
            const exitCode = await exec.exec('echo', ['hello'])

            console.log(exitCode)

exec packages provides getExecOutput function to retrieve stdout and stderr from executed command:

on: push

jobs:
  use-get-exec-output:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/github-script@v9
        with:
          script: |
            const {
              exitCode,
              stdout,
              stderr
            } = await exec.getExecOutput('echo', ['hello']);

            console.log(exitCode, stdout, stderr)