diff --git a/.github/workflows/licensed.yml b/.github/workflows/licensed.yml index 15709f1ce..e8eb6d0d6 100644 --- a/.github/workflows/licensed.yml +++ b/.github/workflows/licensed.yml @@ -19,7 +19,7 @@ jobs: - uses: actions/checkout@v4 with: fetch-depth: 0 # prefer to use a full fetch for licensed workflows - - uses: ruby/setup-ruby@28c4deda893d5a96a6b2d958c5b47fc18d65c9d3 # v1.213.0 + - uses: ruby/setup-ruby@354a1ad156761f5ee2b7b13fa8e09943a5e8d252 # v1.229.0 with: ruby-version: ruby - uses: github/setup-licensed@v1 diff --git a/README.md b/README.md index 43c29f13f..6fe8ae7e6 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,31 @@ This action makes it easy to quickly write a script in your workflow that uses the GitHub API and the workflow run context. +### Note + +Thank you for your interest in this GitHub action, however, right now we are not taking contributions. + +We continue to focus our resources on strategic areas that help our customers be successful while making developers' lives easier. While GitHub Actions remains a key part of this vision, we are allocating resources towards other areas of Actions and are not taking contributions to this repository at this time. The GitHub public roadmap is the best place to follow along for any updates on features we’re working on and what stage they’re in. + +We are taking the following steps to better direct requests related to GitHub Actions, including: + +1. We will be directing questions and support requests to our [Community Discussions area](https://github.com/orgs/community/discussions/categories/actions) + +2. High Priority bugs can be reported through Community Discussions or you can report these to our support team https://support.github.com/contact/bug-report. + +3. Security Issues should be handled as per our [security.md](security.md) + +We will still provide security updates for this project and fix major breaking changes during this time. + +You are welcome to still raise bugs in this repo. + +### This action + To use this action, provide an input named `script` that contains the body of an asynchronous JavaScript function call. The following arguments will be provided: -- `octokit` (and `github`) A pre-authenticated - [octokit/rest.js](https://octokit.github.io/rest.js) client _instance_ with pagination plugins +- `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 @@ -59,6 +79,31 @@ For example, `github.issues.createComment` in V4 becomes `github.rest.issues.cre See [development.md](/docs/development.md). +## Passing inputs to the script + +Actions expressions are evaluated before the `script` is passed to the action, so the result of any expressions +*will be evaluated as JavaScript code*. + +It's highly recommended to *not* evaluate expressions directly in the `script` to avoid +[script injections](https://docs.github.com/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections) +and potential `SyntaxError`s when the expression is not valid JavaScript code (particularly when it comes to improperly escaped strings). + +To pass inputs, set `env` vars on the action step and reference them in your script with `process.env`: + +```yaml +- uses: actions/github-script@v7 + env: + TITLE: ${{ github.event.pull_request.title }} + with: + script: | + const title = process.env.TITLE; + if (title.startsWith('octocat')) { + console.log("PR title starts with 'octocat'"); + } else { + console.error("PR title did not start with 'octocat'"); + } +``` + ## Reading step results The return value of the script will be in the step's outputs under the @@ -102,14 +147,14 @@ By default, requests made with the `github` instance will not be retried. You ca result-encoding: string retries: 3 script: | - octokit.rest.issues.get({ + github.rest.issues.get({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, }) ``` -In this example, request failures from `octokit.rest.issues.get()` will be retried up to 3 times. +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: @@ -121,7 +166,7 @@ You can also configure which status codes should be exempt from retries via the retries: 3 retry-exempt-status-codes: 400,401 script: | - octokit.rest.issues.get({ + github.rest.issues.get({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, @@ -162,7 +207,7 @@ jobs: - uses: actions/github-script@v7 with: script: | - octokit.rest.issues.createComment({ + github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, @@ -184,7 +229,7 @@ jobs: - uses: actions/github-script@v7 with: script: | - octokit.rest.issues.addLabels({ + github.rest.issues.addLabels({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, @@ -209,12 +254,12 @@ jobs: // 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 = octokit.rest.issues.listForRepo.endpoint.merge({ + const opts = github.rest.issues.listForRepo.endpoint.merge({ ...context.issue, creator, state: 'all' }) - const issues = await octokit.paginate(opts) + const issues = await github.paginate(opts) for (const issue of issues) { if (issue.number === context.issue.number) { @@ -226,7 +271,7 @@ jobs: } } - await octokit.rest.issues.createComment({ + await github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, @@ -252,7 +297,7 @@ jobs: with: script: | const diff_url = context.payload.pull_request.diff_url - const result = await octokit.request(diff_url) + const result = await github.request(diff_url) console.log(result) ``` @@ -289,7 +334,7 @@ jobs: name: context.repo.repo, label: 'wontfix' } - const result = await octokit.graphql(query, variables) + const result = await github.graphql(query, variables) console.log(result) ``` @@ -310,13 +355,13 @@ jobs: with: script: | const script = require('./path/to/script.js') - console.log(script({octokit, context})) + console.log(script({github, context})) ``` And then export a function from your module: ```javascript -module.exports = ({octokit, context}) => { +module.exports = ({github, context}) => { return context.payload.client_payload.value } ``` @@ -350,15 +395,15 @@ jobs: with: script: | const script = require('./path/to/script.js') - await script({octokit, context, core}) + await script({github, context, core}) ``` And then export an async function from your module: ```javascript -module.exports = async ({octokit, context, core}) => { +module.exports = async ({github, context, core}) => { const {SHA} = process.env - const commit = await octokit.rest.repos.getCommit({ + const commit = await github.rest.repos.getCommit({ owner: context.repo.owner, repo: context.repo.repo, ref: `${SHA}` @@ -444,27 +489,6 @@ export default async ({ core, context }) => { }; ``` -### 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 @@ -487,10 +511,52 @@ jobs: with: github-token: ${{ secrets.MY_PAT }} script: | - octokit.rest.issues.addLabels({ + github.rest.issues.addLabels({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, labels: ['Triage'] }) ``` + +### Using exec package + +The provided [@actions/exec](https://github.com/actions/toolkit/tree/main/packages/exec) package allows to execute command or tools in a cross platform way: + +```yaml +on: push + +jobs: + use-exec: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/github-script@v7 + with: + script: | + const exitCode = await exec.exec('echo', ['hello']) + + console.log(exitCode) +``` + +`exec` packages provides `getExecOutput` function to retrieve stdout and stderr from executed command: + +```yaml +on: push + +jobs: + use-get-exec-output: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/github-script@v7 + with: + script: | + const { + exitCode, + stdout, + stderr + } = await exec.getExecOutput('echo', ['hello']); + + console.log(exitCode, stdout, stderr) +```