This action makes it easy to quickly write a script in your workflow that uses the GitHub API and the workflow run context.
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:
githubA pre-authenticated octokit/rest.js client with pagination pluginscontextAn object containing the context of the workflow runcoreA reference to the @actions/core packageglobA reference to the @actions/glob packageioA reference to the @actions/io packageexecA reference to the @actions/exec packagerequireA proxy wrapper around the normal Node.jsrequireto 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-wrappedrequire, there is an escape hatch available:__original_require__is the original value ofrequirewithout 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.
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/.
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.
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.
See development.md.
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@v7
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'");
}The return value of the script will be in the step's outputs under the "result" key.
- uses: actions/github-script@v7
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.
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@v7
id: my-script
with:
result-encoding: string
script: return "I will be string (not JSON) encoded!"By default, requests made with the github instance will not be retried. You can configure this with the retries option:
- uses: actions/github-script@v7
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@v7
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)
Note that github-token is optional in this action, and the input is there
in case you need to use a non-default tok
10000
en.
By default, github-script will use the token provided to your workflow.
- name: View context attributes
uses: actions/github-script@v7
with:
script: console.log(context)on:
issues:
types: [opened]
jobs:
comment:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v7
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: 'đź‘‹ Thanks for reporting!'
})on:
issues:
types: [opened]
jobs:
apply-label:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v7
with:
script: |
github.rest.issues.addLabels({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
labels: ['Triage']
})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@v7
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 ✨`
})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@v7
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.
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@v7
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)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@v7
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.
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@v7
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)
}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@v7
with:
script: |
const execa = require('execa')
const { stdout } = await execa('echo', ['hello', 'world'])
console.log(stdout)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@v7
with:
script: |
const { default: printStuff } = await import('${{ github.workspace }}/src/print-stuff.js')
await printStuff()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-scriptAnd 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;
};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
on:
issues:
types: [opened]
jobs:
apply-label:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v7
with:
github-token: ${{ secrets.MY_PAT }}
script: |
github.rest.issues.addLabels({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
labels: ['Triage']
})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@v7
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@v7
with:
script: |
const {
exitCode,
stdout,
stderr
} = await exec.getExecOutput('echo', ['hello']);
console.log(exitCode, stdout, stderr)