Skip to content

Commit fb0feb9

Browse files
jclemjclem
authored
Add licensed workflow badge
1 parent 21ae42f commit fb0feb9

File tree

1 file changed

+225
-1
lines changed

1 file changed

+225
-1
lines changed

‎README.md

+225-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,228 @@
1-
# 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)
1+
# 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)
2+
3+
This action makes it easy to quickly write a script in your workflow that
4+
uses the GitHub API and the workflow run context.
5+
6+
In order to use this action, a `script` input is provided. The value of that
7+
input should be the body of an asynchronous function call. The following
8+
arguments will be provided:
9+
10+
- `github` A pre-authenticated
11+
[octokit/rest.js](https://github.com/octokit/rest.js) client
12+
- `context` An object containing the [context of the workflow
13+
run](https://github.com/actions/toolkit/blob/main/packages/github/src/context.ts)
14+
- `core` A reference to the [@actions/core](https://github.com/actions/toolkit/tree/main/packages/core) package
15+
- `io` A reference to the [@actions/io](https://github.com/actions/toolkit/tree/main/packages/io) package
16+
17+
Since the `script` is just a function body, these values will already be
18+
defined, so you don't have to (see examples below).
19+
20+
See [octokit/rest.js](https://octokit.github.io/rest.js/) for the API client
21+
documentation.
22+
23+
**Note** This action is still a bit of an experiment—the API may change in
24+
future versions. 🙂
25+
26+
## Development
27+
28+
See [development.md](/docs/development.md).
29+
30+
## Reading step results
31+
32+
The return value of the script will be in the step's outputs under the
33+
"result" key.
34+
35+
```yaml
36+
- uses: actions/github-script@v2
37+
id: set-result
38+
with:
39+
script: return "Hello!"
40+
result-encoding: string
41+
- name: Get result
42+
run: echo "${{steps.set-result.outputs.result}}"
43+
```
44+
45+
See ["Result encoding"](#result-encoding) for details on how the encoding of
46+
these outputs can be changed.
47+
48+
## Result encoding
49+
50+
By default, the JSON-encoded return value of the function is set as the "result" in the
51+
output of a github-script step. For some workflows, string encoding is preferred. This option can be set using the
52+
`result-encoding` input:
53+
54+
```yaml
55+
- uses: actions/github-script@v2
56+
id: my-script
57+
with:
58+
github-token: ${{secrets.GITHUB_TOKEN}}
59+
result-encoding: string
60+
script: return "I will be string (not JSON) encoded!"
61+
```
62+
63+
## Examples
64+
65+
Note that `github-token` is optional in this action, and the input is there
66+
in case you need to use a non-default token.
67+
68+
By default, github-script will use the token provided to your workflow.
69+
70+
### Comment on an issue
71+
72+
```yaml
73+
on:
74+
issues:
75+
types: [opened]
76+
77+
jobs:
78+
comment:
79+
runs-on: ubuntu-latest
80+
steps:
81+
- uses: actions/github-script@v2
82+
with:
83+
github-token: ${{secrets.GITHUB_TOKEN}}
84+
script: |
85+
github.issues.createComment({
86+
issue_number: context.issue.number,
87+
owner: context.repo.owner,
88+
repo: context.repo.repo,
89+
body: '👋 Thanks for reporting!'
90+
})
91+
```
92+
93+
### Apply a label to an issue
94+
95+
```yaml
96+
on:
97+
issues:
98+
types: [opened]
99+
100+
jobs:
101+
apply-label:
102+
runs-on: ubuntu-latest
103+
steps:
104+
- uses: actions/github-script@v2
105+
with:
106+
github-token: ${{secrets.GITHUB_TOKEN}}
107+
script: |
108+
github.issues.addLabels({
109+
issue_number: context.issue.number,
110+
owner: context.repo.owner,
111+
repo: context.repo.repo,
112+
labels: ['Triage']
113+
})
114+
```
115+
116+
### Welcome a first-time contributor
117+
118+
```yaml
119+
on: pull_request
120+
121+
jobs:
122+
welcome:
123+
runs-on: ubuntu-latest
124+
steps:
125+
- uses: actions/github-script@v2
126+
with:
127+
github-token: ${{secrets.GITHUB_TOKEN}}
128+
script: |
129+
// Get a list of all issues created by the PR opener
130+
// See: https://octokit.github.io/rest.js/#pagination
131+
const creator = context.payload.sender.login
132+
const opts = github.issues.listForRepo.endpoint.merge({
133+
...context.issue,
134+
creator,
135+
state: 'all'
136+
})
137+
const issues = await github.paginate(opts)
138+
139+
for (const issue of issues) {
140+
if (issue.number === context.issue.number) {
141+
continue
142+
}
143+
144+
if (issue.pull_request) {
145+
return // Creator is already a contributor.
146+
}
147+
}
148+
149+
await github.issues.createComment({
150+
issue_number: context.issue.number,
151+
owner: context.repo.owner,
152+
repo: context.repo.repo,
153+
body: 'Welcome, new contributor!'
154+
})
155+
```
156+
157+
### Download data from a URL
158+
159+
You can use the `github` object to access the Octokit API. For
160+
instance, `github.request`
161+
162+
```yaml
163+
on: pull_request
164+
165+
jobs:
166+
diff:
167+
runs-on: ubuntu-latest
168+
steps:
169+
- uses: actions/github-script@v2
170+
with:
171+
github-token: ${{secrets.GITHUB_TOKEN}}
172+
script: |
173+
const diff_url = context.payload.pull_request.diff_url
174+
const result = await github.request(diff_url)
175+
console.log(result)
176+
```
177+
178+
_(Note that this particular example only works for a public URL, where the
179+
diff URL is publicly accessible. Getting the diff for a private URL requires
180+
using the API.)_
181+
182+
This will print the full diff object in the screen; `result.data` will
183+
contain the actual diff text.
184+
185+
### Run a separate file
186+
187+
If you don't want to inline your entire script that you want to run, you can
188+
use a separate JavaScript module in your repository like so:
189+
190+
```yaml
191+
on: push
192+
193+
jobs:
194+
echo-input:
195+
runs-on: ubuntu-latest
196+
steps:
197+
- uses: actions/checkout@v2
198+
- uses: actions/github-script@v2
199+
with:
200+
script: |
201+
const script = require(`${process.env.GITHUB_WORKSPACE}/path/to/script.js`)
202+
console.log(script({github, context}))
203+
```
204+
205+
*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).*
206+
207+
And then export a function from your module:
208+
209+
```javascript
210+
module.exports = (github, context) => {
211+
return context.payload.client_payload.value
212+
}
213+
```
214+
215+
You can also use async functions in this manner, as long as you `await` it in
216+
the inline script.
217+
218+
Note that because you can't `require` things like the GitHub context or
219+
Actions Toolkit libraries, you'll want to pass them as arguments to your
220+
external function.
221+
222+
Additionally, you'll want to use the [checkout
223+
action](https://github.com/actions/checkout) to make sure your script file is
224+
available.
225+
2226

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

0 commit comments

Comments
 (0)