actions/github-script

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:

• github A pre-authenticated octokit/rest.js client
• context An object containing the context of the workflow run
• core A reference to the @actions/core package
• io A reference to the @actions/io package

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. 🙂

Development

See development.md.

Reading step results

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.

Result encoding

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!"

Examples

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.

Comment on an issue

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!'
            })

Apply a label to an issue

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']
            })

Welcome a first-time contributor

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!'
            })

Download data from a URL

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.

Run a separate file

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@v2
        with:
          script: |
            const script = require(`${process.env.GITHUB_WORKSPACE}/path/to/script.js`)
            console.log(script({github, context}))

Note that the script path given to require() must be an absolute path in this case, hence using GITHUB_WORKSPACE.

And then export a function from your module:

module.exports = (github, context) => {
  return context.payload.client_payload.value
}

You can also use async functions in this manner, as long as you await it in the inline script.

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.

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:

• github A pre-authenticated octokit/rest.js client
• context An object containing the context of the workflow run
• core A reference to the @actions/core package
• io A reference to the @actions/io package

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. 🙂

Development

See development.md.

Reading step results

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.

Result encoding

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!"

Examples

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.

Comment on an issue

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!'
            })

Apply a label to an issue

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']
            })

Welcome a first-time contributor

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!'
            })

Download data from a URL

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.

Run a separate file

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@v2
        with:
          script: |
            const script = require(`${process.env.GITHUB_WORKSPACE}/path/to/script.js`)
            console.log(script({github, context}))

Note that the script path given to require() must be an absolute path in this case, hence using GITHUB_WORKSPACE.

And then export a function from your module:

module.exports = (github, context) => {
  return context.payload.client_payload.value
}

You can also use async functions in this manner, as long as you await it in the inline script.

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.