Skip to content

Commit 37c2031

Browse files
osherosher
committed
feat: add script-file input for lint-friendly external JS scripts
Closes #714 Inline `script` is a YAML string — invisible to linters and IDEs. The common workaround was wrapping a `require` call inside the inline script, which still needs boilerplate and assumes a path convention. New optional `script-file` input that accepts a path to a JS file. The file must `module.exports` an async function receiving the standard IoC dependency bag (`github`, `octokit`, `getOctokit`, `context`, `core`, `exec`, `glob`, `io`, `require`). ```yaml - uses: actions/checkout@v4 - uses: actions/github-script@v9 with: script-file: .github/scripts/my-script.js ``` `script` and `script-file` are mutually exclusive — exactly one must be provided. Relative paths resolve against `$GITHUB_WORKSPACE`; absolute paths are used as-is. - `action.yml` — adds `script-file` input; makes `script` optional - `src/script-file.ts` — path resolution and script loading logic - `src/args.ts` — `AsyncFunctionArguments` extracted from `async-function.ts` so neither execution path depends on the other - `src/main.ts` — mutual-exclusion validation; dispatches to the right execution path - `types/non-webpack-require.ts` — corrects `__non_webpack_require__` type from deprecated `NodeRequire` / wrong `NodeJS.RequireResolve` to `NodeJS.Require` - `__test__/script-file.test.ts` — 10 tests covering path resolution, arg forwarding, error cases - `README.md` — new `## Script file` section with usage, IoC bag table, path resolution rules - `.github/fixtures/script-file/` — fixture JS files for integration tests - `.github/workflows/integration.yml` — 10 new integration test jobs: happy path (relative path, absolute path, all IoC args, json/string encoding, require-in-file) and error cases (both inputs set, neither set, nonexistent file, non-function export, file:// protocol)
1 parent 3a2844b commit 37c2031

18 files changed

Lines changed: 495 additions & 60 deletions

‎.github/fixtures/script-file/all-args.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
module.exports = async ({github, octokit, getOctokit, context, core, exec, glob, io, require}) => {
2+
return [github, octokit, getOctokit, context, core, exec, glob, io, require]
3+
.map(arg => typeof arg)
4+
.every(t => t === 'function' || t === 'object')
5+
}

‎.github/fixtures/script-file/basic.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
module.exports = async () => 'hello from script-file'

‎.github/fixtures/script-file/json-return.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
module.exports = async ({context}) => ({repo: context.repo.repo, owner: context.repo.owner})

‎.github/fixtures/script-file/not-a-function.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
module.exports = 42

‎.github/fixtures/script-file/sibling-caller.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
module.exports = async ({require}) => require('./sibling-module').value

‎.github/fixtures/script-file/sibling-module.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
module.exports = {value: 'loaded-by-require'}

‎.github/workflows/integration.yml‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -361,3 +361,174 @@ jobs:
361361
echo $'::error::\u274C' "Expected base-url to equal '$expected', got $actual"
362362
exit 1
363363
fi
364+
365+
test-script-file-basic:
366+
name: 'Integration test: script-file - relative path, string return'
367+
runs-on: ubuntu-latest
368+
steps:
369+
- uses: actions/checkout@v4
370+
- id: act
371+
uses: ./
372+
with:
373+
script-file: .github/fixtures/script-file/basic.js
374+
result-encoding: string
375+
- run: |
376+
expected="hello from script-file"
377+
if [[ "${{ steps.act.outputs.result }}" != "$expected" ]]; then
378+
echo $'::error::❌' "Expected '$expected', got ${{ steps.act.outputs.result }}"
379+
exit 1
380+
fi
381+
echo $'✅ Test passed' | tee -a $GITHUB_STEP_SUMMARY
382+
383+
test-script-file-absolute-path:
384+
name: 'Integration test: script-file - absolute path'
385+
runs-on: ubuntu-latest
386+
steps:
387+
- uses: actions/checkout@v4
388+
- id: act
389+
uses: ./
390+
with:
391+
script-file: ${{ github.workspace }}/.github/fixtures/script-file/basic.js
392+
result-encoding: string
393+
- run: |
394+
expected="hello from script-file"
395+
if [[ "${{ steps.act.outputs.result }}" != "$expected" ]]; then
396+
echo $'::error::❌' "Expected '$expected', got ${{ steps.act.outputs.result }}"
397+
exit 1
398+
fi
399+
echo $'✅ Test passed' | tee -a $GITHUB_STEP_SUMMARY
400+
401+
test-script-file-all-ioc-args:
402+
name: 'Integration test: script-file - all IoC args available'
403+
runs-on: ubuntu-latest
404+
steps:
405+
- uses: actions/checkout@v4
406+
- id: act
407+
uses: ./
408+
with:
409+
script-file: .github/fixtures/script-file/all-args.js
410+
- run: |
411+
if [[ "${{ steps.act.outputs.result }}" != "true" ]]; then
412+
echo $'::error::❌' "Expected all IoC args to be present, got ${{ steps.act.outputs.result }}"
413+
exit 1
414+
fi
415+
echo $'✅ Test passed' | tee -a $GITHUB_STEP_SUMMARY
416+
417+
test-script-file-result-encoding-json:
418+
name: 'Integration test: script-file - result-encoding json'
419+
runs-on: ubuntu-latest
420+
steps:
421+
- uses: actions/checkout@v4
422+
- id: act
423+
uses: ./
424+
with:
425+
script-file: .github/fixtures/script-file/json-return.js
426+
- run: |
427+
expected='{"repo":"${{ github.event.repository.name }}","owner":"${{ github.repository_owner }}"}'
428+
if [[ "${{ steps.act.outputs.result }}" != "$expected" ]]; then
429+
echo $'::error::❌' "Expected '$expected', got ${{ steps.act.outputs.result }}"
430+
exit 1
431+
fi
432+
echo $'✅ Test passed' | tee -a $GITHUB_STEP_SUMMARY
433+
434+
test-script-file-require-in-file:
435+
name: 'Integration test: script-file - require inside script file'
436+
runs-on: ubuntu-latest
437+
steps:
438+
- uses: actions/checkout@v4
439+
- id: act
440+
uses: ./
441+
with:
442+
script-file: .github/fixtures/script-file/sibling-caller.js
443+
result-encoding: string
444+
- run: |
445+
expected="loaded-by-require"
446+
if [[ "${{ steps.act.outputs.result }}" != "$expected" ]]; then
447+
echo $'::error::❌' "Expected '$expected', got ${{ steps.act.outputs.result }}"
448+
exit 1
449+
fi
450+
echo $'✅ Test passed' | tee -a $GITHUB_STEP_SUMMARY
451+
452+
test-script-file-conflict-both:
453+
name: 'Integration test: script-file - fails when both script and script-file are set'
454+
runs-on: ubuntu-latest
455+
steps:
456+
- uses: actions/checkout@v4
457+
- id: act
458+
continue-on-error: true
459+
uses: ./
460+
with:
461+
script: return 1
462+
script-file: .github/fixtures/script-file/basic.js
463+
- run: |
464+
if [[ "${{ steps.act.outcome }}" != "failure" ]]; then
465+
echo $'::error::❌' "Expected step to fail when both inputs are set"
466+
exit 1
467+
fi
468+
echo $'✅ Test passed' | tee -a $GITHUB_STEP_SUMMARY
469+
470+
test-script-file-conflict-neither:
471+
name: 'Integration test: script-file - fails when neither script nor script-file is set'
472+
runs-on: ubuntu-latest
473+
steps:
474+
- uses: actions/checkout@v4
475+
- id: act
476+
continue-on-error: true
477+
uses: ./
478+
- run: |
479+
if [[ "${{ steps.act.outcome }}" != "failure" ]]; then
480+
echo $'::error::❌' "Expected step to fail when no input is set"
481+
exit 1
482+
fi
483+
echo $'✅ Test passed' | tee -a $GITHUB_STEP_SUMMARY
484+
485+
test-script-file-nonexistent-file:
486+
name: 'Integration test: script-file - fails on nonexistent file'
487+
runs-on: ubuntu-latest
488+
steps:
489+
- uses: actions/checkout@v4
490+
- id: act
491+
continue-on-error: true
492+
uses: ./
493+
with:
494+
script-file: .github/fixtures/script-file/does-not-exist.js
495+
- run: |
496+
if [[ "${{ steps.act.outcome }}" != "failure" ]]; then
497+
echo $'::error::❌' "Expected step to fail for nonexistent file"
498+
exit 1
499+
fi
500+
echo $'✅ Test passed' | tee -a $GITHUB_STEP_SUMMARY
501+
502+
test-script-file-non-function-export:
503+
name: 'Integration test: script-file - fails when file does not export a function'
504+
runs-on: ubuntu-latest
505+
steps:
506+
- uses: actions/checkout@v4
507+
- id: act
508+
continue-on-error: true
509+
uses: ./
510+
with:
511+
script-file: .github/fixtures/script-file/not-a-function.js
512+
- run: |
513+
if [[ "${{ steps.act.outcome }}" != "failure" ]]; then
514+
echo $'::error::❌' "Expected step to fail for non-function export"
515+
exit 1
516+
fi
517+
echo $'✅ Test passed' | tee -a $GITHUB_STEP_SUMMARY
518+
519+
test-script-file-file-protocol-rejected:
520+
name: 'Integration test: script-file - fails for file:// protocol'
521+
runs-on: ubuntu-latest
522+
steps:
523+
- uses: actions/checkout@v4
524+
- id: act
525+
continue-on-error: true
526+
uses: ./
527+
with:
528+
script-file: file://${{ github.workspace }}/.github/fixtures/script-file/basic.js
529+
- run: |
530+
if [[ "${{ steps.act.outcome }}" != "failure" ]]; then
531+
echo $'::error::❌' "Expected step to fail for file:// protocol"
532+
exit 1
533+
fi
534+
echo $'✅ Test passed' | tee -a $GITHUB_STEP_SUMMARY

‎README.md‎

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,9 @@ You are welcome to still raise bugs in this repo.
2727

2828
### This action
2929

30-
To use this action, provide an input named `script` that contains the body of an asynchronous JavaScript function call.
31-
The following arguments will be provided:
30+
To use this action, provide either a `script` input (the body of an async function, inline in your workflow YAML) or a `script-file` input (a path to a JS file that `module.exports` an async function). Exactly one of the two must be provided.
31+
32+
The following arguments are available to both forms:
3233

3334
- `github` A pre-authenticated
3435
[octokit/rest.js](https://octokit.github.io/rest.js) client with pagination plugins
@@ -201,6 +202,42 @@ By default, the following status codes will not be retried: `400, 401, 403, 404,
201202

202203
These retries are implemented using the [octokit/plugin-retry.js](https://github.com/octokit/plugin-retry.js) plugin. The retries use [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) to space out retries. ([source](https://github.com/octokit/plugin-retry.js/blob/9a2443746c350b3beedec35cf26e197ea318a261/src/error-request.ts#L13))
203204

205+
## Script file
206+
207+
Instead of providing the `script` inline, you can use `script-file` to point to a JS file in your repository. The file must `module.exports` an async function — making it a proper module that linters and IDEs can fully analyse, with no boilerplate `require` scaffold needed.
208+
209+
```yaml
210+
- uses: actions/checkout@v4
211+
- uses: actions/github-script@v9
212+
with:
213+
script-file: .github/scripts/my-script.js
214+
```
215+
216+
```js
217+
// .github/scripts/my-script.js
218+
module.exports = async ({github, context, core}) => {
219+
// destructure only what you need
220+
}
221+
```
222+
223+
The function receives a single [IoC](https://en.wikipedia.org/wiki/Inversion_of_control) dependency bag (defined in [`src/args.ts`](src/args.ts)). Its members are the same as those available to the inline `script`:
224+
225+
| Name | Description |
226+
|---|---|
227+
| `github` | Pre-authenticated [octokit/rest.js](https://octokit.github.io/rest.js) client |
228+
| `octokit` | Alias for `github` |
229+
| `getOctokit` | Factory for additional authenticated Octokit clients (see [Creating additional clients](#creating-additional-clients-with-getoctokit)) |
230+
| `context` | [Workflow run context](https://github.com/actions/toolkit/blob/main/packages/github/src/context.ts) |
231+
| `core` | [@actions/core](https://github.com/actions/toolkit/tree/main/packages/core) |
232+
| `exec` | [@actions/exec](https://github.com/actions/toolkit/tree/main/packages/exec) |
233+
| `glob` | [@actions/glob](https://github.com/actions/toolkit/tree/main/packages/glob) |
234+
| `io` | [@actions/io](https://github.com/actions/toolkit/tree/main/packages/io) |
235+
| `require` | Wrapped `require` that resolves relative paths and local `node_modules` |
236+
237+
**Path resolution:** relative paths are resolved against `$GITHUB_WORKSPACE`; absolute paths are used as-is. The `file://` protocol is not supported.
238+
239+
`script` and `script-file` are mutually exclusive — exactly one must be provided.
240+
204241
## Examples
205242

206243
Note that `github-token` is optional in this action, and the input is there

‎__test__/script-file.test.ts‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
import * as path from 'node:path'
2+
import * as os from 'node:os'
3+
import * as fs from 'node:fs'
4+
import {callScriptFile, resolveScriptFilePath} from '../src/script-file'
5+
6+
describe('resolveScriptFilePath', () => {
7+
test('rejects file:// protocol', () => {
8+
expect(() => resolveScriptFilePath('file:///some/path.js')).toThrow(
9+
'"script-file" must not use the "file://" protocol'
10+
)
11+
})
12+
13+
test('returns absolute path as-is', () => {
14+
const abs = '/absolute/path/to/script.js'
15+
expect(resolveScriptFilePath(abs)).toEqual(abs)
16+
})
17+
18+
test('resolves relative path against GITHUB_WORKSPACE when set', () => {
19+
const original = process.env['GITHUB_WORKSPACE']
20+
process.env['GITHUB_WORKSPACE'] = '/workspace'
21+
try {
22+
expect(resolveScriptFilePath('scripts/run.js')).toEqual(
23+
'/workspace/scripts/run.js'
24+
)
25+
} finally {
26+
if (original === undefined) {
27+
delete process.env['GITHUB_WORKSPACE']
28+
} else {
29+
process.env['GITHUB_WORKSPACE'] = original
30+
}
31+
}
32+
})
33+
34+
test('resolves relative path against cwd when GITHUB_WORKSPACE is unset', () => {
35+
const original = process.env['GITHUB_WORKSPACE']
36+
delete process.env['GITHUB_WORKSPACE']
37+
try {
38+
expect(resolveScriptFilePath('scripts/run.js')).toEqual(
39+
path.resolve(process.cwd(), 'scripts/run.js')
40+
)
41+
} finally {
42+
if (original !== undefined) {
43+
process.env['GITHUB_WORKSPACE'] = original
44+
}
45+
}
46+
})
47+
})
48+
49+
describe('callScriptFile', () => {
50+
let tmpDir: string
51+
52+
beforeEach(() => {
53+
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'github-script-test-'))
54+
})
55+
56+
afterEach(() => {
57+
fs.rmSync(tmpDir, {recursive: true, force: true})
58+
})
59+
60+
test('calls the exported function with args', async () => {
61+
const scriptPath = path.join(tmpDir, 'script.js')
62+
fs.writeFileSync(
63+
scriptPath,
64+
'module.exports = async ({core}) => core.value'
65+
)
66+
67+
// eslint-disable-next-line @typescript-eslint/no-require-imports
68+
const result = await callScriptFile(scriptPath, require, {
69+
core: {value: 42}
70+
} as never)
71+
72+
expect(result).toEqual(42)
73+
})
74+
75+
test('forwards all injected args to the exported function', async () => {
76+
const scriptPath = path.join(tmpDir, 'all-args.js')
77+
fs.writeFileSync(
78+
scriptPath,
79+
`module.exports = async (args) => Object.keys(args).sort()`
80+
)
81+
82+
const args = {
83+
github: {},
84+
octokit: {},
85+
getOctokit: () => null,
86+
context: {},
87+
core: {},
88+
exec: {},
89+
glob: {},
90+
io: {},
91+
require: require,
92+
__original_require__: require
93+
}
94+
95+
// eslint-disable-next-line @typescript-eslint/no-require-imports
96+
const result = await callScriptFile(scriptPath, require, args as never)
97+
98+
expect(result).toEqual(Object.keys(args).sort())
99+
})
100+
101+
test('throws when file does not export a function', async () => {
102+
const scriptPath = path.join(tmpDir, 'not-a-fn.js')
103+
fs.writeFileSync(scriptPath, 'module.exports = 42')
104+
105+
await expect(
106+
// eslint-disable-next-line @typescript-eslint/no-require-imports
107+
callScriptFile(scriptPath, require, {} as never)
108+
).rejects.toThrow('"script-file" must export a function, got number')
109+
})
110+
111+
test('throws when file does not exist', async () => {
112+
const scriptPath = path.join(tmpDir, 'nonexistent.js')
113+
114+
await expect(
115+
// eslint-disable-next-line @typescript-eslint/no-require-imports
116+
callScriptFile(scriptPath, require, {} as never)
117+
).rejects.toThrow()
118+
})
119+
120+
test('propagates rejection from the exported function', async () => {
121+
const scriptPath = path.join(tmpDir, 'throws.js')
122+
fs.writeFileSync(
123+
scriptPath,
124+
"module.exports = async () => { throw new Error('boom') }"
125+
)
126+
127+
await expect(
128+
// eslint-disable-next-line @typescript-eslint/no-require-imports
129+
callScriptFile(scriptPath, require, {} as never)
130+
).rejects.toThrow('boom')
131+
})
132+
133+
test('rejects file:// path before loading', async () => {
134+
await expect(
135+
// eslint-disable-next-line @typescript-eslint/no-require-imports
136+
callScriptFile('file:///some/path.js', require, {} as never)
137+
).rejects.toThrow('"script-file" must not use the "file://" protocol')
138+
})
139+
})

‎action.yml‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,11 @@ branding:
66
icon: code
77
inputs:
88
script:
9-
description: The script to run
10-
required: true
9+
description: The body of an async function to run (mutually exclusive with script-file)
10+
required: false
11+
script-file:
12+
description: Path to a JS file that module.exports an async function receiving {github, octokit, getOctokit, context, core, exec, glob, io, require} (mutually exclusive with script)
13+
required: false
1114
github-token:
1215
description: The GitHub token used to create an authenticated client
1316
default: ${{ github.token }}

0 commit comments

Comments
 (0)