This action makes it easy to quickly write a script in your workflow that uses the GitHub API and the workflow run context.
In order to use this action, a script input is provided. The value of that
input should be the body of an asynchronous 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 packagerequireIs available, with some caveats:- The location of the module that runs this action is where the Actions
runner downloads the github-script action to, so the
requirepassed to your script is actually a proxy that intercepts calls to require relative paths and transforms them into an absolute path in the working directory, instead. - If you want to require an npm module in your working directory, you still
need to specify the relative path, including
node_modules, such as./node_modules/lodash. - If for some reason you need the non-wrapped
require, there is an escape hatch available:__original_require__is the original value ofrequirewithout our wrapping applied.
- The location of the module that runs this action is where the Actions
runner downloads the github-script action to, so the
Since the script is just a function body, these values will already be
defined, so you don't have to (see examples below).
See octokit/rest.js for the API client documentation.
Note This action is still a bit of an experiment—the API may change in future versions. 🙂
See development.md.
The return value of the script will be in the step's outputs under the "result" key.
- uses: actions/github-script@v3
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@v3
id: my-script
with:
github-token: ${{secrets.GITHUB_TOKEN}}
result-encoding: string
script: return "I will be string (not JSON) encoded!"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@v3
with:
script: console.log(context)on:
issues:
types: [opened]
jobs:
comment:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v3
with:
github-token: ${{secrets.GITHUB_TOKEN}}
script: |
github.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@v3
with:
github-token: ${{secrets.GITHUB_TOKEN}}
script: |
github.issues.addLabels({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
labels: ['Triage']
})on: pull_request
jobs:
welcome:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v3
with:
github-token: ${{secrets.GITHUB_TOKEN}}
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.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.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: 'Welcome, new contributor!'
})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@v3
with:
github-token: ${{secrets.GITHUB_TOKEN}}
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@v3
with:
github-token: ${{secrets.GITHUB_TOKEN}}
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@v2
- uses: actions/github-script@v3
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@v2
- uses: actions/github-script@v3
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.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:
on: push
jobs:
echo-input:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-node@v2
with:
node-version: 14
- run: npm ci
# or one-off:
- run: npm install execa
- uses: actions/github-script@v3
with:
script: |
const execa = require(`./node_modules/execa`)
const { stdout } = await execa('echo', ['hello', 'world'])
console.log(stdout)(Note that at this time, one still has to specify node_modules in the
require path for modules in the working directory of the step that is
running. Hopefully we will have a solution for this in the future, but not
quite, yet.)
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@v3
env:
FIRST_NAME: Mona
LAST_NAME: Octocat
with:
script: |
const { FIRST_NAME, LAST_NAME } = process.env
console.log(`Hello ${FIRST_NAME} ${LAST_NAME}`)