diff --git a/README.md b/README.md index fb34352..f1afe0e 100644 --- a/README.md +++ b/README.md @@ -226,226 +226,3 @@ external function. Additionally, you'll want to use the [checkout action](https://github.com/actions/checkout) 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](https://github.com/octokit/rest.js) client -- `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 -- `io` A reference to the [@actions/io](https://github.com/actions/toolkit/tree/main/packages/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](https://octokit.github.io/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](/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@v3 - 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@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 - -```yaml -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 - -```yaml -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 - -```yaml -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` - -```yaml -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: - -```yaml -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`](https://docs.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables#default-environment-variables)._ - -And then export a function from your module: - -```javascript -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](https://github.com/actions/checkout) to make sure your script file is -available.