From fb0feb9324d07280c5f37dd77a9f45a809435c95 Mon Sep 17 00:00:00 2001 From: Jonathan Clem Date: Thu, 6 Aug 2020 21:26:37 -0400 Subject: [PATCH] Add licensed workflow badge --- README.md | 226 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 225 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a3197e0..bee62cb 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,228 @@ -# github-script ![.github/workflows/integration.yml](https://github.com/actions/github-script/workflows/.github/workflows/integration.yml/badge.svg?event=push) ![.github/workflows/ci.yml](https://github.com/actions/github-script/workflows/.github/workflows/ci.yml/badge.svg?event=push) +# github-script ![.github/workflows/integration.yml](https://github.com/actions/github-script/workflows/.github/workflows/integration.yml/badge.svg?event=push) ![.github/workflows/ci.yml](https://github.com/actions/github-script/workflows/.github/workflows/ci.yml/badge.svg?event=push) ![.github/workflows/licensed.yml](https://github.com/actions/github-script/workflows/Licensed/badge.svg?event=push) + +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@v2 + 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@v2 + 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@v2 + 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@v2 + 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@v2 + 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@v2 + 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. + This action makes it easy to quickly write a script in your workflow that uses the GitHub API and the workflow run context.