diff --git a/README.md b/README.md index 4963283..d4879a7 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,61 @@ -# Sweep or sleep: Check the Github API limit and act on the remaining requests +# Sweep or sleep (Github API quota action step) [![GitHub Super-Linter](https://github.com/actions/typescript-action/actions/workflows/linter.yml/badge.svg)](https://github.com/super-linter/super-linter) ![CI](https://github.com/actions/typescript-action/actions/workflows/ci.yml/badge.svg) -This action can be used to obtain the remaining Github API quota and act -accordingly. +**Sweep or sleep** is a humble Github action step, which allows to easily check your remaining Github API quota and act accordingly. If your balance drops below your specified lower bound, you can kill (sweep) your workflow run or wait (sleep) until your allotment renews. The step will also set a `${GITHUB_REMAINING_API_QUOTA}` environment variable for your convenience. + +## Usage + +The most simple way to use this action step is within a separate job that precedes the main job. Since the `api_quota_check` job will fail, if your API quota is too low, `some_other_job` will not not even start. + +If you set `actionToTake` to _sleep_ instead, the `api_quota_check` will delay it's completion until shortly after the allotted quota renews. This does not guarantee the successful completion of your job (in particular if multiple workflows are running in parallel), but maximizes the chances. Stop wasting your precious API requests on attempting workflow runs that certainly will not succeed. + +```yaml +jobs: + api_quota_check: + runs-on: ubuntu-latest + + steps: + - uses: MatthiasZepper/sweep_or_sleep_action + id: check_quota + with: + lowerBound: 20 + actionToTake: "sweep" + + some_other_job: + needs: api_quota_check +``` + +Since + +```yaml +jobs: + api_quota_check: + runs-on: ubuntu-latest + outputs: + remaining: ${{ steps.check_quota.outputs.remaining }} + + steps: + - uses: MatthiasZepper/sweep_or_sleep_action + id: check_quota + with: + lowerBound: 990 + actionToTake: "sweep" + + - name: Print quota + run: echo "Remaining API requests ${{steps.check_quota.outputs.remaining}}" + + some_other_job: + needs: api_quota_check +``` ## Development ### Initial Setup After you've cloned the repository to your local machine or codespace, you'll -need to perform some initial setup steps before you can develop your action. +need to perform some initial setup steps: > [!NOTE] > diff --git a/src/main.ts b/src/main.ts index 0c83e4f..f18aafe 100644 --- a/src/main.ts +++ b/src/main.ts @@ -55,7 +55,7 @@ export async function run(): Promise { if (remaining < 0 || reset < 0) { core.setFailed('Github API rateLimit could not be retrieved.') } else { - core.exportVariable('remaining', remaining) + core.exportVariable('GITHUB_REMAINING_API_QUOTA', remaining) core.setOutput('remaining', remaining) if (remaining > lowerBound) { diff --git a/src/sleep.ts b/src/sleep.ts index 864c2fb..948e890 100644 --- a/src/sleep.ts +++ b/src/sleep.ts @@ -6,7 +6,6 @@ export async function sleep(milliseconds: number): Promise { return new Promise(resolve => { if (isNaN(milliseconds)) { - console.warn(milliseconds) throw new Error('milliseconds not a number') }