From 56bdc6c318bf8445991a0ffe2937052a20443851 Mon Sep 17 00:00:00 2001 From: Viktor Lott Date: Mon, 3 Jul 2023 10:30:03 +0200 Subject: [PATCH 1/8] 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. --- README.md | 19 +++++ docs/alternative-setup.md | 154 ++++++++++++++++++++++++++++++++++++++ package.json | 4 +- src/async-function.ts | 2 +- types/async-function.d.ts | 20 +++++ 5 files changed, 197 insertions(+), 2 deletions(-) create mode 100644 docs/alternative-setup.md create mode 100644 types/async-function.d.ts diff --git a/README.md b/README.md index 29e29456..323df9a5 100644 --- a/README.md +++ b/README.md @@ -419,6 +419,25 @@ jobs: await printStuff() ``` +### Use scripts with jsDoc support + +If you want type support for your scripts, you could use the the command below to install the +`github-script` type declaration. +```sh +$ npm i -D @types/github-script@github:actions/github-script +``` + +And then add the `jsDoc` declaration to your script like this: +```js +// @ts-check +/** @param {import('@types/github-script').AsyncFunctionArguments} AsyncFunctionArguments */ +export default async ({ core, context }) => { + core.debug("Running something at the moment"); + return context.actor; +}; +``` +For an alternative setup, please read (alternative-setup)[./docs/alternative-setup.md]. + ### Use env as input You can set env vars to use them in your script: diff --git a/docs/alternative-setup.md b/docs/alternative-setup.md new file mode 100644 index 00000000..573d79a8 --- /dev/null +++ b/docs/alternative-setup.md @@ -0,0 +1,154 @@ +## Alternative setup + +### Example repository structure +In this example we're using the repo structure below, but you are free +to structure it how ever you like. +``` +root # Your repository + ├── .github + │ ├── ... + │ └── workflows + │ ├── ... + │ └── ci-workflow.yml + ├── ... + ├── actions + │ ├── action.yml (optional) + │ └── ci-test.js + ├── ... + └── package.json +``` + +### 1. Install the github-script type +```sh +$ npm i -D @types/github-script@github:actions/github-script +``` + + +### 2. Create `ci-test.mjs` file +```js +// @ts-check +/** @param {import('@types/github-script').AsyncFunctionArguments} AsyncFunctionArguments */ +export default async ({ core, context }) => { + core.debug("Running something at the moment"); + return context.actor; +}; +``` + +### 3. Create `ci-workflow.yml` file +```yml +on: push + +permissions: + pull-requests: read + contents: read + +jobs: + example: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 + with: + node-version: 16 + + - run: npm ci + - uses: actions/github-script@v6 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + result-encoding: string + script: | + const { default: script } = await import('${{ github.workspace }}/actions/ci-test.js'); + return await script({ github, context, core, exec, glob, io, fetch, __original_require__ }); +``` + + +## Cleaner setup (Optional) + +Note that the `ci-workflow.yml` example above can be kind of tedious once you add more of them. So +to address this, one could instead use `composite` actions. +### The `action.yml` file +```yml +name: Typed GitHub Script +author: GitHub +description: Run simple scripts using the GitHub client +branding: + color: blue + icon: code +inputs: + script: + description: The path to script (e.g actions/ci-test.js) + required: true + github-token: + description: The GitHub token used to create an authenticated client + default: ${{ github.token }} + required: false + debug: + 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. + default: ${{ runner.debug == '1' }} + user-agent: + description: An optional user-agent string + default: actions/github-script + previews: + description: A comma-separated list of API previews to accept + result-encoding: + description: Either "string" or "json" (default "json")—how the result will be encoded + default: json + retries: + description: The number of times to retry a request + default: "0" + retry-exempt-status-codes: + description: A comma separated list of status codes that will NOT be retried e.g. "400,500". No effect unless `retries` is set + default: 400,401,403,404,422 # from https://github.com/octokit/plugin-retry.js/blob/9a2443746c350b3beedec35cf26e197ea318a261/src/index.ts#L14 + +outputs: + result: + description: The return value of the script, stringified with `JSON.stringify` + value: ${{ steps.github-script-result.outputs.result }} + +runs: + using: "composite" + steps: + - uses: actions/github-script@v6 + id: github-script-result + with: + github-token: ${{ inputs.github-token }} + result-encoding: ${{ inputs.result-encoding }} + debug: ${{ inputs.debug }} + user-agent: ${{ inputs.user-agent }} + previews: ${{ inputs.previews }} + retries: ${{ inputs.retries }} + retry-exempt-status-codes: ${{ inputs.retry-exempt-status-codes }} + script: | + const { default: script } = await import(process.env.GITHUB_ACTION_PATH + '/${{ inputs.script }}'); + return await script({ github, context, core, exec, glob, io, fetch, __original_require__ }); +``` + + +### The `ci-workflow.yml` file +Note that we only need to specify the script here because the path will be +resolved to the `uses: ./actions` path by `process.env.GITHUB_ACTION_PATH`. +i.e the same folder as we are executing the action from. +```yml +on: push + +permissions: + pull-requests: read + contents: read + +jobs: + example: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 + with: + node-version: 16 + + - run: npm ci + - uses: ./actions + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + result-encoding: string + script: ci-test.js +``` + diff --git a/package.json b/package.json index 6cc8dfa0..1ce8de22 100644 --- a/package.json +++ b/package.json @@ -5,9 +5,11 @@ "author": "GitHub", "license": "MIT", "main": "dist/index.js", + "types": "types/async-function.d.ts", "private": true, "scripts": { - "build": "ncc build src/main.ts", + "build": "npm run build:types && ncc build src/main.ts", + "build:types": "tsc src/async-function.ts -t es5 --declaration --allowJs --emitDeclarationOnly --outDir types", "format:check": "prettier --check src __test__", "format:write": "prettier --write src __test__", "lint": "eslint src __test__", diff --git a/src/async-function.ts b/src/async-function.ts index 8acd0d5c..8b38e641 100644 --- a/src/async-function.ts +++ b/src/async-function.ts @@ -8,7 +8,7 @@ import fetch from 'node-fetch' const AsyncFunction = Object.getPrototypeOf(async () => null).constructor -type AsyncFunctionArguments = { +export declare type AsyncFunctionArguments = { context: Context core: typeof core github: InstanceType diff --git a/types/async-function.d.ts b/types/async-function.d.ts new file mode 100644 index 00000000..b4d6a8e8 --- /dev/null +++ b/types/async-function.d.ts @@ -0,0 +1,20 @@ +/// +import * as core from '@actions/core'; +import * as exec from '@actions/exec'; +import { Context } from '@actions/github/lib/context'; +import { GitHub } from '@actions/github/lib/utils'; +import * as glob from '@actions/glob'; +import * as io from '@actions/io'; +import fetch from 'node-fetch'; +export declare type AsyncFunctionArguments = { + context: Context; + core: typeof core; + github: InstanceType; + exec: typeof exec; + glob: typeof glob; + io: typeof io; + fetch: typeof fetch; + require: NodeRequire; + __original_require__: NodeRequire; +}; +export declare function callAsyncFunction(args: AsyncFunctionArguments, source: string): Promise; From ba13a89bc902a7b7afbdcb3e3bab38d740a7d573 Mon Sep 17 00:00:00 2001 From: Viktorlo Date: Fri, 28 Jul 2023 11:30:13 +0200 Subject: [PATCH 2/8] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 323df9a5..35d53af1 100644 --- a/README.md +++ b/README.md @@ -421,7 +421,7 @@ jobs: ### Use scripts with jsDoc support -If you want type support for your scripts, you could use the the command below to install the +If you want type support for your scripts, you could use the command below to install the `github-script` type declaration. ```sh $ npm i -D @types/github-script@github:actions/github-script From c857fcb22bcf36100e60a6b7a5d4b6750a99e941 Mon Sep 17 00:00:00 2001 From: Viktorlo Date: Fri, 28 Jul 2023 11:34:17 +0200 Subject: [PATCH 3/8] Update alternative-setup.md --- docs/alternative-setup.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/alternative-setup.md b/docs/alternative-setup.md index 573d79a8..d597ca87 100644 --- a/docs/alternative-setup.md +++ b/docs/alternative-setup.md @@ -13,7 +13,7 @@ root # Your repository ├── ... ├── actions │ ├── action.yml (optional) - │ └── ci-test.js + │ └── ci-test.mjs ├── ... └── package.json ``` @@ -57,7 +57,7 @@ jobs: github-token: ${{ secrets.GITHUB_TOKEN }} result-encoding: string script: | - const { default: script } = await import('${{ github.workspace }}/actions/ci-test.js'); + const { default: script } = await import('${{ github.workspace }}/actions/ci-test.mjs'); return await script({ github, context, core, exec, glob, io, fetch, __original_require__ }); ``` @@ -76,7 +76,7 @@ branding: icon: code inputs: script: - description: The path to script (e.g actions/ci-test.js) + description: The path to script (e.g actions/ci-test.mjs) required: true github-token: description: The GitHub token used to create an authenticated client @@ -125,7 +125,7 @@ runs: ### The `ci-workflow.yml` file -Note that we only need to specify the script here because the path will be +Note that we only need to specify the script name here because the path will be resolved to the `uses: ./actions` path by `process.env.GITHUB_ACTION_PATH`. i.e the same folder as we are executing the action from. ```yml @@ -149,6 +149,6 @@ jobs: with: github-token: ${{ secrets.GITHUB_TOKEN }} result-encoding: string - script: ci-test.js + script: ci-test.mjs ``` From 21446ed76be3bc5e409bf96f5d8b9ceaee5383db Mon Sep 17 00:00:00 2001 From: Viktor Lott Date: Fri, 18 Aug 2023 09:30:09 +0200 Subject: [PATCH 4/8] Remove alternative setup documentation --- README.md | 1 - docs/alternative-setup.md | 154 -------------------------------------- 2 files changed, 155 deletions(-) delete mode 100644 docs/alternative-setup.md diff --git a/README.md b/README.md index 35d53af1..9b235a11 100644 --- a/README.md +++ b/README.md @@ -436,7 +436,6 @@ export default async ({ core, context }) => { return context.actor; }; ``` -For an alternative setup, please read (alternative-setup)[./docs/alternative-setup.md]. ### Use env as input diff --git a/docs/alternative-setup.md b/docs/alternative-setup.md deleted file mode 100644 index d597ca87..00000000 --- a/docs/alternative-setup.md +++ /dev/null @@ -1,154 +0,0 @@ -## Alternative setup - -### Example repository structure -In this example we're using the repo structure below, but you are free -to structure it how ever you like. -``` -root # Your repository - ├── .github - │ ├── ... - │ └── workflows - │ ├── ... - │ └── ci-workflow.yml - ├── ... - ├── actions - │ ├── action.yml (optional) - │ └── ci-test.mjs - ├── ... - └── package.json -``` - -### 1. Install the github-script type -```sh -$ npm i -D @types/github-script@github:actions/github-script -``` - - -### 2. Create `ci-test.mjs` file -```js -// @ts-check -/** @param {import('@types/github-script').AsyncFunctionArguments} AsyncFunctionArguments */ -export default async ({ core, context }) => { - core.debug("Running something at the moment"); - return context.actor; -}; -``` - -### 3. Create `ci-workflow.yml` file -```yml -on: push - -permissions: - pull-requests: read - contents: read - -jobs: - example: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: 16 - - - run: npm ci - - uses: actions/github-script@v6 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - result-encoding: string - script: | - const { default: script } = await import('${{ github.workspace }}/actions/ci-test.mjs'); - return await script({ github, context, core, exec, glob, io, fetch, __original_require__ }); -``` - - -## Cleaner setup (Optional) - -Note that the `ci-workflow.yml` example above can be kind of tedious once you add more of them. So -to address this, one could instead use `composite` actions. -### The `action.yml` file -```yml -name: Typed GitHub Script -author: GitHub -description: Run simple scripts using the GitHub client -branding: - color: blue - icon: code -inputs: - script: - description: The path to script (e.g actions/ci-test.mjs) - required: true - github-token: - description: The GitHub token used to create an authenticated client - default: ${{ github.token }} - required: false - debug: - 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. - default: ${{ runner.debug == '1' }} - user-agent: - description: An optional user-agent string - default: actions/github-script - previews: - description: A comma-separated list of API previews to accept - result-encoding: - description: Either "string" or "json" (default "json")—how the result will be encoded - default: json - retries: - description: The number of times to retry a request - default: "0" - retry-exempt-status-codes: - description: A comma separated list of status codes that will NOT be retried e.g. "400,500". No effect unless `retries` is set - default: 400,401,403,404,422 # from https://github.com/octokit/plugin-retry.js/blob/9a2443746c350b3beedec35cf26e197ea318a261/src/index.ts#L14 - -outputs: - result: - description: The return value of the script, stringified with `JSON.stringify` - value: ${{ steps.github-script-result.outputs.result }} - -runs: - using: "composite" - steps: - - uses: actions/github-script@v6 - id: github-script-result - with: - github-token: ${{ inputs.github-token }} - result-encoding: ${{ inputs.result-encoding }} - debug: ${{ inputs.debug }} - user-agent: ${{ inputs.user-agent }} - previews: ${{ inputs.previews }} - retries: ${{ inputs.retries }} - retry-exempt-status-codes: ${{ inputs.retry-exempt-status-codes }} - script: | - const { default: script } = await import(process.env.GITHUB_ACTION_PATH + '/${{ inputs.script }}'); - return await script({ github, context, core, exec, glob, io, fetch, __original_require__ }); -``` - - -### The `ci-workflow.yml` file -Note that we only need to specify the script name here because the path will be -resolved to the `uses: ./actions` path by `process.env.GITHUB_ACTION_PATH`. -i.e the same folder as we are executing the action from. -```yml -on: push - -permissions: - pull-requests: read - contents: read - -jobs: - example: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: 16 - - - run: npm ci - - uses: ./actions - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - result-encoding: string - script: ci-test.mjs -``` - From ea121b86f93250013496c8ae6b1852ce432aed23 Mon Sep 17 00:00:00 2001 From: Rob Anderson Date: Fri, 20 Oct 2023 10:16:28 -0600 Subject: [PATCH 5/8] add base-url option --- action.yml | 3 +++ src/main.ts | 5 ++++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/action.yml b/action.yml index 858c88f5..742549b3 100644 --- a/action.yml +++ b/action.yml @@ -29,6 +29,9 @@ inputs: retry-exempt-status-codes: description: A comma separated list of status codes that will NOT be retried e.g. "400,500". No effect unless `retries` is set default: 400,401,403,404,422 # from https://github.com/octokit/plugin-retry.js/blob/9a2443746c350b3beedec35cf26e197ea318a261/src/index.ts#L14 + base-url: + description: The root of the API URL of the GHES instance to which to connect. + required: false outputs: result: description: The return value of the script, stringified with `JSON.stringify` diff --git a/src/main.ts b/src/main.ts index 658cee06..f3c41b08 100644 --- a/src/main.ts +++ b/src/main.ts @@ -18,6 +18,7 @@ main().catch(handleError) type Options = { log?: Console userAgent?: string + baseUrl?: string previews?: string[] retry?: RetryOptions request?: RequestRequestOptions @@ -28,6 +29,7 @@ async function main(): Promise { const debug = core.getBooleanInput('debug') const userAgent = core.getInput('user-agent') const previews = core.getInput('previews') + const baseUrl = core.getInput('base-url') const retries = parseInt(core.getInput('retries')) const exemptStatusCodes = parseNumberArray( core.getInput('retry-exempt-status-codes') @@ -43,7 +45,8 @@ async function main(): Promise { userAgent: userAgent || undefined, previews: previews ? previews.split(',') : undefined, retry: retryOpts, - request: requestOpts + request: requestOpts, + baseUrl: baseUrl || undefined } const github = getOctokit(token, opts, retry, requestLog) From e8957ff5ee76db74d98a47fa052d129482ee87a1 Mon Sep 17 00:00:00 2001 From: Rob Anderson Date: Mon, 23 Oct 2023 16:35:17 -0600 Subject: [PATCH 6/8] generate dist changes for addition of base-url --- dist/index.js | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/dist/index.js b/dist/index.js index 5eb9aacf..3d30c49a 100644 --- a/dist/index.js +++ b/dist/index.js @@ -15220,6 +15220,7 @@ async function main() { const debug = core.getBooleanInput('debug'); const userAgent = core.getInput('user-agent'); const previews = core.getInput('previews'); + const baseUrl = core.getInput('base-url'); const retries = parseInt(core.getInput('retries')); const exemptStatusCodes = parseNumberArray(core.getInput('retry-exempt-status-codes')); const [retryOpts, requestOpts] = getRetryOptions(retries, exemptStatusCodes, utils.defaults); @@ -15228,7 +15229,8 @@ async function main() { userAgent: userAgent || undefined, previews: previews ? previews.split(',') : undefined, retry: retryOpts, - request: requestOpts + request: requestOpts, + baseUrl: baseUrl || undefined }; const github = (0,lib_github.getOctokit)(token, opts, plugin_retry_dist_node/* retry */.XD, dist_node/* requestLog */.g); const script = core.getInput('script', { required: true }); From ef8023aa4abe571b1300d698453c06ce31edceb0 Mon Sep 17 00:00:00 2001 From: Rob Anderson Date: Mon, 23 Oct 2023 19:35:20 -0400 Subject: [PATCH 7/8] Update action.yml Co-authored-by: Josh Gross --- action.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/action.yml b/action.yml index 742549b3..373b1766 100644 --- a/action.yml +++ b/action.yml @@ -30,7 +30,7 @@ inputs: description: A comma separated list of status codes that will NOT be retried e.g. "400,500". No effect unless `retries` is set default: 400,401,403,404,422 # from https://github.com/octokit/plugin-retry.js/blob/9a2443746c350b3beedec35cf26e197ea318a261/src/index.ts#L14 base-url: - description: The root of the API URL of the GHES instance to which to connect. + description: An optional GitHub REST API URL to connect to a different GitHub instance. required: false outputs: result: From 5940a763782c6e1af9993f61930458ed8e5e4b1d Mon Sep 17 00:00:00 2001 From: Rob Anderson Date: Mon, 23 Oct 2023 17:37:49 -0600 Subject: [PATCH 8/8] add example to description of base-url parameter --- action.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/action.yml b/action.yml index 373b1766..39615fd4 100644 --- a/action.yml +++ b/action.yml @@ -30,7 +30,7 @@ inputs: description: A comma separated list of status codes that will NOT be retried e.g. "400,500". No effect unless `retries` is set default: 400,401,403,404,422 # from https://github.com/octokit/plugin-retry.js/blob/9a2443746c350b3beedec35cf26e197ea318a261/src/index.ts#L14 base-url: - description: An optional GitHub REST API URL to connect to a different GitHub instance. + description: An optional GitHub REST API URL to connect to a different GitHub instance. For example, https://my.github-enterprise-server.com/api/v3 required: false outputs: result: