Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 56bdc6c

Browse filesBrowse files
viktorlottviktorlott
committed
Expose async-function argument type
We are exposing the async-function argument type for jsDoc type declaration support. This means that we now could do: "npm i -D @types/github-script@github:actions/github-script" and the add: "@param {import('@types/github-script').AsyncFunctionArguments} AsyncFunctionArguments". This could obviously be done in other ways too, like using "@typed-actions/github-script" instead. But it seems better to use the actual source repository instead of a third-party library to import the type declaration.
1 parent 6f00a0b commit 56bdc6c
Copy full SHA for 56bdc6c

File tree

5 files changed

+197
-2
lines changed
Filter options

5 files changed

+197
-2
lines changed

‎README.md

Copy file name to clipboardExpand all lines: README.md
+19Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -419,6 +419,25 @@ jobs:
419419
await printStuff()
420420
```
421421

422+
### Use scripts with jsDoc support
423+
424+
If you want type support for your scripts, you could use the the command below to install the
425+
`github-script` type declaration.
426+
```sh
427+
$ npm i -D @types/github-script@github:actions/github-script
428+
```
429+
430+
And then add the `jsDoc` declaration to your script like this:
431+
```js
432+
// @ts-check
433+
/** @param {import('@types/github-script').AsyncFunctionArguments} AsyncFunctionArguments */
434+
export default async ({ core, context }) => {
435+
core.debug("Running something at the moment");
436+
return context.actor;
437+
};
438+
```
439+
For an alternative setup, please read (alternative-setup)[./docs/alternative-setup.md].
440+
422441
### Use env as input
423442

424443
You can set env vars to use them in your script:

‎docs/alternative-setup.md

Copy file name to clipboard
+154Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
## Alternative setup
2+
3+
### Example repository structure
4+
In this example we're using the repo structure below, but you are free
5+
to structure it how ever you like.
6+
```
7+
root # Your repository
8+
├── .github
9+
│ ├── ...
10+
│ └── workflows
11+
│ ├── ...
12+
│ └── ci-workflow.yml
13+
├── ...
14+
├── actions
15+
│ ├── action.yml (optional)
16+
│ └── ci-test.js
17+
├── ...
18+
└── package.json
19+
```
20+
21+
### 1. Install the github-script type
22+
```sh
23+
$ npm i -D @types/github-script@github:actions/github-script
24+
```
25+
26+
27+
### 2. Create `ci-test.mjs` file
28+
```js
29+
// @ts-check
30+
/** @param {import('@types/github-script').AsyncFunctionArguments} AsyncFunctionArguments */
31+
export default async ({ core, context }) => {
32+
core.debug("Running something at the moment");
33+
return context.actor;
34+
};
35+
```
36+
37+
### 3. Create `ci-workflow.yml` file
38+
```yml
39+
on: push
40+
41+
permissions:
42+
pull-requests: read
43+
contents: read
44+
45+
jobs:
46+
example:
47+
runs-on: ubuntu-latest
48+
steps:
49+
- uses: actions/checkout@v3
50+
- uses: actions/setup-node@v3
51+
with:
52+
node-version: 16
53+
54+
- run: npm ci
55+
- uses: actions/github-script@v6
56+
with:
57+
github-token: ${{ secrets.GITHUB_TOKEN }}
58+
result-encoding: string
59+
script: |
60+
const { default: script } = await import('${{ github.workspace }}/actions/ci-test.js');
61+
return await script({ github, context, core, exec, glob, io, fetch, __original_require__ });
62+
```
63+
64+
65+
## Cleaner setup (Optional)
66+
67+
Note that the `ci-workflow.yml` example above can be kind of tedious once you add more of them. So
68+
to address this, one could instead use `composite` actions.
69+
### The `action.yml` file
70+
```yml
71+
name: Typed GitHub Script
72+
author: GitHub
73+
description: Run simple scripts using the GitHub client
74+
branding:
75+
color: blue
76+
icon: code
77+
inputs:
78+
script:
79+
description: The path to script (e.g actions/ci-test.js)
80+
required: true
81+
github-token:
82+
description: The GitHub token used to create an authenticated client
83+
default: ${{ github.token }}
84+
required: false
85+
debug:
86+
description: Whether to tell the GitHub client to log details of its requests. true or false. Default is to run in debug mode when the GitHub Actions step debug logging is turned on.
87+
default: ${{ runner.debug == '1' }}
88+
user-agent:
89+
description: An optional user-agent string
90+
default: actions/github-script
91+
previews:
92+
description: A comma-separated list of API previews to accept
93+
result-encoding:
94+
description: Either "string" or "json" (default "json")—how the result will be encoded
95+
default: json
96+
retries:
97+
description: The number of times to retry a request
98+
default: "0"
99+
retry-exempt-status-codes:
100+
description: A comma separated list of status codes that will NOT be retried e.g. "400,500". No effect unless `retries` is set
101+
default: 400,401,403,404,422 # from https://github.com/octokit/plugin-retry.js/blob/9a2443746c350b3beedec35cf26e197ea318a261/src/index.ts#L14
102+
103+
outputs:
104+
result:
105+
description: The return value of the script, stringified with `JSON.stringify`
106+
value: ${{ steps.github-script-result.outputs.result }}
107+
108+
runs:
109+
using: "composite"
110+
steps:
111+
- uses: actions/github-script@v6
112+
id: github-script-result
113+
with:
114+
github-token: ${{ inputs.github-token }}
115+
result-encoding: ${{ inputs.result-encoding }}
116+
debug: ${{ inputs.debug }}
117+
user-agent: ${{ inputs.user-agent }}
118+
previews: ${{ inputs.previews }}
119+
retries: ${{ inputs.retries }}
120+
retry-exempt-status-codes: ${{ inputs.retry-exempt-status-codes }}
121+
script: |
122+
const { default: script } = await import(process.env.GITHUB_ACTION_PATH + '/${{ inputs.script }}');
123+
return await script({ github, context, core, exec, glob, io, fetch, __original_require__ });
124+
```
125+
126+
127+
### The `ci-workflow.yml` file
128+
Note that we only need to specify the script here because the path will be
129+
resolved to the `uses: ./actions` path by `process.env.GITHUB_ACTION_PATH`.
130+
i.e the same folder as we are executing the action from.
131+
```yml
132+
on: push
133+
134+
permissions:
135+
pull-requests: read
136+
contents: read
137+
138+
jobs:
139+
example:
140+
runs-on: ubuntu-latest
141+
steps:
142+
- uses: actions/checkout@v3
143+
- uses: actions/setup-node@v3
144+
with:
145+
node-version: 16
146+
147+
- run: npm ci
148+
- uses: ./actions
149+
with:
150+
github-token: ${{ secrets.GITHUB_TOKEN }}
151+
result-encoding: string
152+
script: ci-test.js
153+
```
154+

‎package.json

Copy file name to clipboardExpand all lines: package.json
+3-1Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,11 @@
55
"author": "GitHub",
66
"license": "MIT",
77
"main": "dist/index.js",
8+
"types": "types/async-function.d.ts",
89
"private": true,
910
"scripts": {
10-
"build": "ncc build src/main.ts",
11+
"build": "npm run build:types && ncc build src/main.ts",
12+
"build:types": "tsc src/async-function.ts -t es5 --declaration --allowJs --emitDeclarationOnly --outDir types",
1113
"format:check": "prettier --check src __test__",
1214
"format:write": "prettier --write src __test__",
1315
"lint": "eslint src __test__",

‎src/async-function.ts

Copy file name to clipboardExpand all lines: src/async-function.ts
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import fetch from 'node-fetch'
88

99
const AsyncFunction = Object.getPrototypeOf(async () => null).constructor
1010

11-
type AsyncFunctionArguments = {
11+
export declare type AsyncFunctionArguments = {
1212
context: Context
1313
core: typeof core
1414
github: InstanceType<typeof GitHub>

‎types/async-function.d.ts

Copy file name to clipboard
+20Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
/// <reference types="node" />
2+
import * as core from '@actions/core';
3+
import * as exec from '@actions/exec';
4+
import { Context } from '@actions/github/lib/context';
5+
import { GitHub } from '@actions/github/lib/utils';
6+
import * as glob from '@actions/glob';
7+
import * as io from '@actions/io';
8+
import fetch from 'node-fetch';
9+
export declare type AsyncFunctionArguments = {
10+
context: Context;
11+
core: typeof core;
12+
github: InstanceType<typeof GitHub>;
13+
exec: typeof exec;
14+
glob: typeof glob;
15+
io: typeof io;
16+
fetch: typeof fetch;
17+
require: NodeRequire;
18+
__original_require__: NodeRequire;
19+
};
20+
export declare function callAsyncFunction<T>(args: AsyncFunctionArguments, source: string): Promise<T>;

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.