base on Write workflows scripting the GitHub API in JavaScript # actions/github-script [](https://github.com/actions/github-script/actions/workflows/integration.yml) [](https://github.com/actions/github-script/actions/workflows/ci.yml) [](https://github.com/actions/github-script/actions/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](https://octokit.github.io/rest.js) client with pagination plugins - `context` An object containing the [context of the workflow run](https://github.com/actions/toolkit/blob/main/packages/github/src/context.ts) - `core` A reference to the [@actions/core](https://github.com/actions/toolkit/tree/main/packages/core) package - `glob` A reference to the [@actions/glob](https://github.com/actions/toolkit/tree/main/packages/glob) package - `io` A reference to the [@actions/io](https://github.com/actions/toolkit/tree/main/packages/io) package - `exec` A reference to the [@actions/exec](https://github.com/actions/toolkit/tree/main/packages/exec) 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](https://octokit.github.io/rest.js/) for the API client documentation. ## Breaking Changes ### V7 Version 7 of this action updated the runtime to Node 20 - https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions All scripts are now run with Node 20 instead of Node 16 and are affected by any breaking changes between Node 16 and 20 The `previews` input now only applies to GraphQL API calls as REST API previews are no longer necessary - https://github.blog/changelog/2021-10-14-rest-api-preview-promotions/. ### 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#runs-for-javascript-actions All scripts are now run with Node 16 instead of Node 12 and are affected by any breaking changes between Node 12 and 16. ### 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](/docs/development.md). ## Reading step results The return value of the script will be in the step's outputs under the "result" key. ```yaml - uses: actions/github-script@v7 id: set-result with: script: return "Hello!" result-encoding: string - name: Get result run: echo "${{steps.set-result.outputs.result}}" ``` See ["Result encoding"](#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: ```yaml - uses: actions/github-script@v7 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: ```yaml - uses: actions/github-script@v7 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: ```yaml - uses: actions/github-script@v7 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)](https://github.com/octokit/plugin-retry.js/blob/9a2443746c350b3beedec35cf26e197ea318a261/src/index.ts#L14). These retries are implemented using the [octokit/plugin-retry.js](https://github.com/octokit/plugin-retry.js) plugin. The retries use [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) to space out retries. ([source](https://github.com/octokit/plugin-retry.js/blob/9a2443746c350b3beedec35cf26e197ea318a261/src/error-request.ts#L13)) ## 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 ```yaml - name: View context attributes uses: actions/github-script@v7 with: script: console.log(context) ``` ### Comment on an issue ```yaml on: issues: types: [opened] jobs: comment: runs-on: ubuntu-latest steps: - uses: actions/github-script@v7 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 ```yaml on: issues: types: [opened] jobs: apply-label: runs-on: ubuntu-latest steps: - uses: actions/github-script@v7 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](https://docs.github.com/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) as the GitHub web interface: ```yaml on: pull_request_target jobs: welcome: runs-on: ubuntu-latest steps: - uses: actions/github-script@v7 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` ```yaml on: pull_request jobs: diff: runs-on: ubuntu-latest steps: - uses: actions/github-script@v7 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. ```yaml jobs: list-issues: runs-on: ubuntu-latest steps: - uses: actions/github-script@v7 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: ```yaml on: push jobs: echo-input: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/github-script@v7 with: script: | const script = require('./path/to/script.js') console.log(script({github, context})) ``` And then export a function from your module: ```javascript 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](https://github.com/actions/checkout) 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: ```yaml on: push jobs: echo-input: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/github-script@v7 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: ```javascript 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: ```yaml on: push jobs: echo-input: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/setup-node@v3 with: node-version: '20.x' - run: npm ci # or one-off: - run: npm install execa - uses: actions/github-script@v7 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`: ```js export default function printStuff() { console.log('stuff') } ``` ```yaml on: push jobs: print-stuff: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/github-script@v7 with: script: | const { default: printStuff } = await import('${{ github.workspace }}/src/print-stuff.js') await printStuff() ``` ### Use scripts with jsDoc support If you want type support for your scripts, you could use the command below to install the `github-script` type declaration. ```sh $ npm i -D @types/github-script@github:actions/github-script ``` And then add the `jsDoc` declaration to your script like this: ```js // @ts-check /** @param {import('@types/github-script').AsyncFunctionArguments} AsyncFunctionArguments */ export default async ({ core, context }) => { core.debug("Running something at the moment"); return context.actor; }; ``` ### Use env as input You can set env vars to use them in your script: ```yaml on: push jobs: echo-input: runs-on: ubuntu-latest steps: - uses: actions/github-script@v7 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](https://docs.github.com/actions/reference/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](https://help.github.com/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) as a secret using the `github-token` input. [Learn more about creating and using encrypted secrets](https://docs.github.com/actions/reference/encrypted-secrets) ```yaml on: issues: types: [opened] jobs: apply-label: runs-on: ubuntu-latest steps: - uses: actions/github-script@v7 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'] }) ``` ", Assign "at most 3 tags" to the expected json: {"id":"4474","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"