actions/github-script actions/github-script

  • Stars
    star
    3,938
  • Rank 10,637 (Top 0.3 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created over 4 years ago
  • Updated about 2 months ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
actions/github-script
github

actions

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Write workflows scripting the GitHub API in JavaScript

actions/github-script

.github/workflows/integration.yml .github/workflows/ci.yml .github/workflows/licensed.yml

This action makes it easy to quickly write a script in your workflow that uses the GitHub API and the workflow run context.

To use this action, provide an input named script that contains the body of an asynchronous function call. The following arguments will be provided:

  • github A pre-authenticated octokit/rest.js client with pagination plugins
  • context An object containing the context of the workflow run
  • core A reference to the @actions/core package
  • glob A reference to the @actions/glob package
  • io A reference to the @actions/io package
  • exec A reference to the @actions/exec package
  • fetch A reference to the node-fetch package
  • require A proxy wrapper around the normal Node.js require to 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-wrapped require, there is an escape hatch available: __original_require__ is the original value of require without our wrapping applied.

Since the script is just a function body, these values will already be defined, so you don't have to import them (see examples below).

See octokit/rest.js for the API client documentation.

Breaking Changes

Breaking changes in V6

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.

Breaking changes in V5

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 via github no longer has REST methods directly. These methods are available via github.rest.* - https://github.com/octokit/plugin-rest-endpoint-methods.js/releases/tag/v5.0.0

For example, github.issues.createComment in V4 becomes github.rest.issues.createComment in V5

github.request, github.paginate, and github.graphql are unchanged.

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@v6
  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@v6
  id: my-script
  with:
    result-encoding: string
    script: return "I will be string (not JSON) encoded!"

Retries

By default, requests made with the github instance will not be retried. You can configure this with the retries option:

- uses: actions/github-script@v6
  id: my-script
  with:
    result-encoding: string
    retries: 3
    script: |
      github.rest.issues.get({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
      })

In this example, request failures from github.rest.issues.get() will be retried up to 3 times.

You can also configure which status codes should be exempt from retries via the retry-exempt-status-codes option:

- uses: actions/github-script@v6
  id: my-script
  with:
    result-encoding: string
    retries: 3
    retry-exempt-status-codes: 400,401
    script: |
      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 the octokit/plugin-retry.js plugin. The retries use exponential backoff to space out retries. (source)

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.

Print the available attributes of context

- name: View context attributes
  uses: actions/github-script@v6
  with:
    script: console.log(context)

Comment on an issue

on:
  issues:
    types: [opened]

jobs:
  comment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v6
        with:
          script: |
            github.rest.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@v6
        with:
          script: |
            github.rest.issues.addLabels({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              labels: ['Triage']
            })

Welcome a first-time contributor

You can format text in comments using the same Markdown syntax as the GitHub web interface:

on: pull_request_target

jobs:
  welcome:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v6
        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.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 ✨`
            })

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@v6
        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.

Run custom GraphQL queries

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@v6
        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)

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@v3
      - uses: actions/github-script@v6
        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.

Run a separate file with an async function

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@v3
      - uses: actions/github-script@v6
        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.rest.repos.getCommit({
    owner: context.repo.owner,
    repo: context.repo.repo,
    ref: `${SHA}`
  })
  core.exportVariable('author', commit.data.commit.author.email)
}

Use npm packages

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@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
      - run: npm ci
      # or one-off:
      - run: npm install execa
      - uses: actions/github-script@v6
        with:
          script: |
            const execa = require('execa')

            const { stdout } = await execa('echo', ['hello', 'world'])

            console.log(stdout)

Use ESM import

To import an ESM file, you'll need to reference your script by an absolute path and ensure you have a package.json file with "type": "module" specified.

For a script in your repository src/print-stuff.js:

export default function printStuff() {
  console.log('stuff')
}
on: push

jobs:
  print-stuff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/github-script@v6
        with:
          script: |
            const { default: printStuff } = await import('${{ github.workspace }}/src/print-stuff.js')

            await printStuff()

Use env as input

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@v6
        env:
          FIRST_NAME: Mona
          LAST_NAME: Octocat
        with:
          script: |
            const { FIRST_NAME, LAST_NAME } = process.env

            console.log(`Hello ${FIRST_NAME} ${LAST_NAME}`)

Using a separate GitHub token

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@v6
        with:
          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']
            })

More Repositories

1

runner-images

GitHub Actions runner images
PowerShell
8,720
star
2

starter-workflows

Accelerating new GitHub Actions workflows
TypeScript
8,466
star
3

toolkit

The GitHub ToolKit for developing GitHub Actions.
TypeScript
4,696
star
4

checkout

Action for checking out a repo
TypeScript
4,634
star
5

runner

The Runner for GitHub Actions 🚀
C#
4,498
star
6

cache

Cache dependencies and build outputs in GitHub Actions
TypeScript
4,263
star
7

actions-runner-controller

Kubernetes controller for GitHub Actions self-hosted runners
Go
4,260
star
8

setup-node

Set up your GitHub Actions workflow with a specific version of node.js
TypeScript
3,639
star
9

upload-artifact

TypeScript
2,908
star
10

typescript-action

Create a TypeScript Action with tests, linting, workflow, publishing, and versioning
TypeScript
1,795
star
11

labeler

An action for automatically labelling pull requests
TypeScript
1,752
star
12

setup-python

Set up your GitHub Actions workflow with a specific version of Python
TypeScript
1,550
star
13

setup-java

Set up your GitHub Actions workflow with a specific version of Java
TypeScript
1,437
star
14

create-release

An Action to create releases via the GitHub Release API
JavaScript
1,324
star
15

setup-go

Set up your GitHub Actions workflow with a specific version of Go
TypeScript
1,314
star
16

download-artifact

TypeScript
1,284
star
17

stale

Marks issues and pull requests that have not had recent interaction
TypeScript
1,254
star
18

javascript-action

Create a JavaScript Action with tests, linting, workflow, publishing, and versioning
JavaScript
911
star
19

setup-dotnet

Set up your GitHub Actions workflow with a specific version of the .NET core sdk
TypeScript
911
star
20

upload-release-asset

An Action to upload a release asset via the GitHub Release API
JavaScript
660
star
21

first-interaction

An action for filtering pull requests and issues from first-time contributors
JavaScript
648
star
22

deploy-pages

GitHub Action to publish artifacts to GitHub Pages for deployments
JavaScript
555
star
23

dependency-review-action

A GitHub Action for detecting vulnerable dependencies and invalid licenses in your PRs
TypeScript
528
star
24

add-to-project

Automate adding issues and pull requests to GitHub projects
TypeScript
455
star
25

delete-package-versions

TypeScript
318
star
26

gh-actions-cache

A GitHub (gh) CLI extension to manage the GitHub Actions caches being used in a GitHub repository.
Go
257
star
27

example-services

Example workflows using service containers
JavaScript
244
star
28

hello-world-javascript-action

A template to demonstrate how to build a JavaScript action.
JavaScript
198
star
29

container-action

Shell
183
star
30

heroku

GitHub Action for interacting with Heroku
HCL
179
star
31

upload-pages-artifact

A composite action for packaging and uploading an artifact that can be deployed to GitHub Pages.
Shell
171
star
32

setup-ruby

Set up your GitHub Actions workflow with a specific version of Ruby
TypeScript
170
star
33

hello-world-docker-action

A template to demonstrate how to build a Docker action.
Shell
154
star
34

setup-elixir

Set up your GitHub Actions workflow with OTP and Elixir
JavaScript
153
star
35

python-versions

Python builds for Actions Runner Images
PowerShell
148
star
36

container-toolkit-action

Template repo for creating container actions using https://github.com/actions/toolkit/
TypeScript
107
star
37

github

Wraps actions-toolkit into an Action for common GitHub automations.
JavaScript
103
star
38

actions-sync

This tool allows GHES administrators to sync Actions to their instances
Go
93
star
39

configure-pages

An action to enable Pages and extract various metadata about a site. It can also be used to configure various static site generators we support as starter workflows.
JavaScript
91
star
40

create-github-app-token

GitHub Action for creating a GitHub App Installation Access Token
JavaScript
86
star
41

setup-haskell

Set up your GitHub Actions workflow with a specific version of Haskell (GHC and Cabal)
TypeScript
69
star
42

node-versions

Node builds for Actions Runner Images
PowerShell
69
star
43

http-client

A lightweight HTTP client optimized for use with actions, TypeScript with generics and async await.
TypeScript
69
star
44

jekyll-build-pages

A simple GitHub Action for producing Jekyll build artifacts compatible with GitHub Pages.
HTML
66
star
45

importer-labs

GitHub Actions Importer helps you plan and automate the migration of Azure DevOps, Bamboo, CircleCI, GitLab, Jenkins, and Travis CI pipelines to GitHub Actions.
Ruby
61
star
46

runner-container-hooks

Runner Container Hooks for GitHub Actions
TypeScript
58
star
47

languageservices

Language services for GitHub Actions workflows and expressions.
TypeScript
50
star
48

go-dependency-submission

Calculates dependencies for a Go build-target and submits the list to the Dependency Submission API
TypeScript
48
star
49

importer-issue-ops

GitHub Actions Importer helps you plan and automate the migration of Azure DevOps, Bamboo, CircleCI, GitLab, Jenkins, and Travis CI pipelines to GitHub Actions.
Ruby
48
star
50

go-versions

Go releases for Actions Runner Images
PowerShell
39
star
51

reusable-workflows

Reusable workflows for developing actions
JavaScript
38
star
52

publish-action

TypeScript
33
star
53

.github

30
star
54

humans.txt

An Action to list out the humans who help feed and tend the robots of GitHub Actions.
JavaScript
28
star
55

versions-package-tools

Libs and tools used to build all *-version tools for GitHub Actions
PowerShell
20
star
56

virtual-environments-packages

Code and scripts used to automate delivery of tool packages used in virtual-environments.
17
star
57

partner-runner-images

About GitHub Actions runner images provided by 3rd parties
7
star
58

boost-versions

Boost builds for Actions Virtual Environments
PowerShell
6
star
59

action-versions

Shell
6
star
60

anno-test

1
star
61

alpine_nodejs

Workflow for redistribution of Node.JS for actions/runner
Dockerfile
1
star