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 function call.
The following arguments will be provided:
github
A pre-authenticated octokit/rest.js client with pagination pluginscontext
An object containing the context of the workflow runcore
A reference to the @actions/core packageglob
A reference to the @actions/glob packageio
A reference to the @actions/io packageexec
A reference to the @actions/exec packagerequire
A proxy wrapper around the normal Node.jsrequire
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-wrappedrequire
, there is an escape hatch available:__original_require__
is the original value ofrequire
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.
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.
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 token.
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@v3
- 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@v3
- 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@v3
- uses: actions/setup-node@v3
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@v3
- 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
github-script
type declaration.
$ npm i -D @types/github-script@github:actions/github-script
And then add the jsDoc
declaration to your script like this:
// @ts-check
/** @param {import('@types/github-script').AsyncFunctionArguments} AsyncFunctionArguments */
export default async ({ core, context }) => {
core.debug("Running something at the moment");
return context.actor;
};
You can set env vars to use them in your script:
on: push
jobs:
echo-input:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v7
env:
FIRST_NAME: Mona
LAST_NAME: Octocat
with:
script: |
const { FIRST_NAME, LAST_NAME } = process.env
console.log(`Hello ${FIRST_NAME} ${LAST_NAME}`)
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']
})