- Notifications
You must be signed in to change notification settings - Fork455
Write workflows scripting the GitHub API in JavaScript
License
actions/github-script
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
This action makes it easy to quickly write a script in your workflow thatuses the GitHub API and the workflow run context.
To use this action, provide an input namedscript that contains the body of an asynchronous JavaScript function call.The following arguments will be provided:
githubA pre-authenticatedoctokit/rest.js client with pagination pluginscontextAn object containing thecontext of the workflowruncoreA 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 enablerequiring relative paths (relative to the current working directory) andrequiring npm packages installed in the current working directory. If forsome reason you need the non-wrappedrequire, there is an escape hatchavailable:__original_require__is the original value ofrequirewithoutour wrapping applied.
Since thescript is just a function body, these values will already bedefined, so you don't have to import them (see examples below).
Seeoctokit/rest.js for the API clientdocumentation.
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
Thepreviews 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 viagithub no longer has REST methods directly. These methods are available viagithub.rest.* -https://github.com/octokit/plugin-rest-endpoint-methods.js/releases/tag/v5.0.0
For example,github.issues.createComment in V4 becomesgithub.rest.issues.createComment in V5
github.request,github.paginate, andgithub.graphql are unchanged.
Seedevelopment.md.
Actions expressions are evaluated before thescript is passed to the action, so the result of any expressionswill be evaluated as JavaScript code.
It's highly recommended tonot evaluate expressions directly in thescript to avoidscript injectionsand potentialSyntaxErrors when the expression is not valid JavaScript code (particularly when it comes to improperly escaped strings).
To pass inputs, setenv vars on the action step and reference them in your script withprocess.env:
-uses:actions/github-script@v7env: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@v7id:set-resultwith:script:return "Hello!"result-encoding:string-name:Get resultrun:echo "${{steps.set-result.outputs.result}}"
See"Result encoding" for details on how the encoding ofthese outputs can be changed.
By default, the JSON-encoded return value of the function is set as the "result" in theoutput of a github-script step. For some workflows, string encoding is preferred. This option can be set using theresult-encoding input:
-uses:actions/github-script@v7id:my-scriptwith:result-encoding:stringscript:return "I will be string (not JSON) encoded!"
By default, requests made with thegithub instance will not be retried. You can configure this with theretries option:
-uses:actions/github-script@v7id:my-scriptwith:result-encoding:stringretries:3script:| github.rest.issues.get({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, })
In this example, request failures fromgithub.rest.issues.get() will be retried up to 3 times.
You can also configure which status codes should be exempt from retries via theretry-exempt-status-codes option:
-uses:actions/github-script@v7id:my-scriptwith:result-encoding:stringretries:3retry-exempt-status-codes:400,401script:| 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 theoctokit/plugin-retry.js plugin. The retries useexponential backoff to space out retries. (source)
Note thatgithub-token is optional in this action, and the input is therein case you need to use a non-default token.
By default, github-script will use the token provided to your workflow.
-name:View context attributesuses:actions/github-script@v7with:script:console.log(context)
on:issues:types:[opened]jobs:comment:runs-on:ubuntu-lateststeps: -uses:actions/github-script@v7with: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-lateststeps: -uses:actions/github-script@v7with: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 sameMarkdown syntax as the GitHub web interface:
on:pull_request_targetjobs:welcome:runs-on:ubuntu-lateststeps: -uses:actions/github-script@v7with: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 thegithub object to access the Octokit API. Forinstance,github.request
on:pull_requestjobs:diff:runs-on:ubuntu-lateststeps: -uses:actions/github-script@v7with: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 thediff URL is publicly accessible. Getting the diff for a private URL requiresusing the API.)
This will print the full diff object in the screen;result.data willcontain the actual diff text.
You can use thegithub.graphql object to run custom GraphQL queries against the GitHub API.
jobs:list-issues:runs-on:ubuntu-lateststeps: -uses:actions/github-script@v7with: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 canuse a separate JavaScript module in your repository like so:
on:pushjobs:echo-input:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -uses:actions/github-script@v7with: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})=>{returncontext.payload.client_payload.value}
Note that because you can'trequire things like the GitHub context orActions Toolkit libraries, you'll want to pass them as arguments to yourexternal function.
Additionally, you'll want to use thecheckoutaction to make sure your script file isavailable.
You can also use async functions in this manner, as long as youawait it inthe inline script.
In your workflow:
on:pushjobs:echo-input:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -uses:actions/github-script@v7env: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.envconstcommit=awaitgithub.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 toprequire, so if you'retrying to require a module inside your own file, you might need to importit externally or pass therequire wrapper to your file:
on:pushjobs:echo-input:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -uses:actions/setup-node@v4with:node-version:'20.x' -run:npm ci# or one-off: -run:npm install execa -uses:actions/github-script@v7with: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 apackage.json file with"type": "module" specified.
For a script in your repositorysrc/print-stuff.js:
exportdefaultfunctionprintStuff(){console.log('stuff')}
on:pushjobs:print-stuff:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -uses:actions/github-script@v7with: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-script
And then add thejsDoc declaration to your script like this:
//@ts-check/**@param {import('@actions/github-script').AsyncFunctionArguments} AsyncFunctionArguments */exportdefaultasync({ core, context})=>{core.debug("Running something at the moment");returncontext.actor;};
TheGITHUB_TOKEN used by default is scoped to the current repository, seeAuthentication in a workflow.
If you need access to a different repository or an API that theGITHUB_TOKEN doesn't have permissions to, you can provide your ownPAT as a secret using thegithub-token input.
Learn more about creating and using encrypted secrets
on:issues:types:[opened]jobs:apply-label:runs-on:ubuntu-lateststeps: -uses:actions/github-script@v7with: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:pushjobs:use-exec:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -uses:actions/github-script@v7with:script:| const exitCode = await exec.exec('echo', ['hello']) console.log(exitCode)
exec packages providesgetExecOutput function to retrieve stdout and stderr from executed command:
on:pushjobs:use-get-exec-output:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -uses:actions/github-script@v7with:script:| const { exitCode, stdout, stderr } = await exec.getExecOutput('echo', ['hello']); console.log(exitCode, stdout, stderr)
About
Write workflows scripting the GitHub API in JavaScript
Topics
Resources
License
Code of conduct
Security policy
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.