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 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 (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@v4
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@v4
id: my-script
with:
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@v4
with:
script: console.log(context)on:
issues:
types: [opened]
jobs:
comment:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v4
with:
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@v4
with:
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@v4
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.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@v4
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@v4
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@v2
- uses: actions/github-script@v4
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@v4
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.
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@v2
- uses: actions/setup-node@v2
with:
node-version: 14
- run: npm ci
# or one-off:
- run: npm install execa
- uses: actions/github-script@v4
with:
script: |
const execa = require('execa')
const { stdout } = await execa('echo', ['hello', 'world'])
console.log(stdout)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@v4
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@v4
with:
github-token: ${{ secrets.MY_PAT }}
script: |
github.issues.addLabels({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
labels: ['Triage']
})