diff --git a/docs/action-debugging.md b/docs/action-debugging.md index af5c88b6..65226920 100644 --- a/docs/action-debugging.md +++ b/docs/action-debugging.md @@ -1,9 +1,23 @@ # Debugging -If the build logs do not provide enough detail on why a build may be failing, some other options exist to assist with troubleshooting. +If the job logs do not provide enough detail on why a job may be failing, some other options exist to assist with troubleshooting. + +## Step Debug Logs +This is the primary way for customers to debug job failures caused by failed steps. + +Step debug logs increase the verbosity of a job's logs during and after a job's execution to assist with troubleshooting. + +Additional log events with the prefix `::debug::` will now also appear in the job's logs, these log events are provided by the Action's author and the runner process. + +### How to Access Step Debug Logs +This flag can be enabled by [setting the secret](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets#creating-encrypted-secrets) `ACTIONS_STEP_DEBUG` to `true`. + +All actions ran while this secret is enabled will show debug events in the [Downloaded Logs](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/managing-a-workflow-run#downloading-logs-and-artifacts) and [Web Logs](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/managing-a-workflow-run#viewing-logs-to-diagnose-failures). ## Runner Diagnostic Logs Runner Diagnostic Logs provide additional log files detailing how the Runner is executing an action. +You need the runner diagnostic logs only if you think there is an infrastructure problem with GitHub Actions and you want the product team to check the logs. + Each file contains different logging information that corresponds to that process: * The Runner process coordinates setting up workers to execute jobs. * The Worker process executes the job. @@ -15,12 +29,3 @@ These log files are enabled by [setting the secret](https://help.github.com/en/a All actions ran while this secret is enabled contain additional diagnostic log files in the `runner-diagnostic-logs` folder of the [log archive](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/managing-a-workflow-run#downloading-logs-and-artifacts). -## Step Debug Logs -Step debug logs increase the verbosity of a job's logs during and after a job's execution to assist with troubleshooting. - -Additional log events with the prefix `::debug::` will now also appear in the job's logs. - -### How to Access Step Debug Logs -This flag can be enabled by [setting the secret](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets#creating-encrypted-secrets) `ACTIONS_STEP_DEBUG` to `true`. - -All actions ran while this secret is enabled will show debug events in the [Downloaded Logs](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/managing-a-workflow-run#downloading-logs-and-artifacts) and [Web Logs](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/managing-a-workflow-run#viewing-logs-to-diagnose-failures). diff --git a/packages/core/README.md b/packages/core/README.md index 457f73cc..5ad27eed 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -82,6 +82,12 @@ try { core.warning('myInput was not set'); } + if (core.isDebug()) { + // curl -v https://github.com + } else { + // curl https://github.com + } + // Do stuff } catch (err) { diff --git a/packages/core/__tests__/core.test.ts b/packages/core/__tests__/core.test.ts index 90235428..020f4a51 100644 --- a/packages/core/__tests__/core.test.ts +++ b/packages/core/__tests__/core.test.ts @@ -177,6 +177,19 @@ describe('@actions/core', () => { it('getState gets wrapper action state', () => { expect(core.getState('TEST_1')).toBe('state_val') }) + + it('isDebug check debug state', () => { + const current = process.env['RUNNER_DEBUG'] + try { + delete process.env.RUNNER_DEBUG + expect(core.isDebug()).toBe(false) + + process.env['RUNNER_DEBUG'] = '1' + expect(core.isDebug()).toBe(true) + } finally { + process.env['RUNNER_DEBUG'] = current + } + }) }) // Assert that process.stdout.write calls called only with the given arguments. diff --git a/packages/core/src/core.ts b/packages/core/src/core.ts index dcaab53e..9072f46a 100644 --- a/packages/core/src/core.ts +++ b/packages/core/src/core.ts @@ -102,6 +102,13 @@ export function setFailed(message: string): void { // Logging Commands //----------------------------------------------------------------------- +/** + * Gets whether Actions Step Debug is on or not + */ +export function isDebug(): boolean { + return process.env['RUNNER_DEBUG'] === '1' +} + /** * Writes debug message to user log * @param message debug message