- Notifications
You must be signed in to change notification settings - Fork0
Write workflows scripting the GitHub API in JavaScript
License
typed-actions/github-script-fork
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 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 packagefetchA reference to thenode-fetch 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 6 of this action updated the runtime to Node 16 -https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#example-using-nodejs-v16
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.
The return value of the script will be in the step's outputs under the"result" key.
-uses:actions/github-script@v6id: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@v6id: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@v6id: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@v6id: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@v6with:script:console.log(context)
on:issues:types:[opened]jobs:comment:runs-on:ubuntu-lateststeps: -uses:actions/github-script@v6with: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@v6with: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@v6with: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@v6with: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@v6with: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@v3 -uses:actions/github-script@v6with: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@v3 -uses:actions/github-script@v6env: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@v3 -uses:actions/setup-node@v3with:node-version:16 -run:npm ci# or one-off: -run:npm install execa -uses:actions/github-script@v6with: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@v3 -uses:actions/github-script@v6with:script:| const { default: printStuff } = await import('${{ github.workspace }}/src/print-stuff.js') await printStuff()
You can set env vars to use them in your script:
on:pushjobs:echo-input:runs-on:ubuntu-lateststeps: -uses:actions/github-script@v6env:FIRST_NAME:MonaLAST_NAME:Octocatwith:script:| const { FIRST_NAME, LAST_NAME } = process.env console.log(`Hello ${FIRST_NAME} ${LAST_NAME}`)
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@v6with: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'] })
About
Write workflows scripting the GitHub API in JavaScript
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Releases
Packages0
Languages
- TypeScript99.1%
- Shell0.9%