diff --git a/assets/images/actions-job-summary-simple-example.png b/assets/images/actions-job-summary-simple-example.png new file mode 100644 index 0000000000..0a64743367 Binary files /dev/null and b/assets/images/actions-job-summary-simple-example.png differ diff --git a/content/actions/learn-github-actions/environment-variables.md b/content/actions/learn-github-actions/environment-variables.md index 5aaf0b3daf..62c448736b 100644 --- a/content/actions/learn-github-actions/environment-variables.md +++ b/content/actions/learn-github-actions/environment-variables.md @@ -157,6 +157,9 @@ We strongly recommend that actions use environment variables to access the files | `GITHUB_RUN_NUMBER` | {% data reusables.actions.run_number_description %} For example, `3`. | | `GITHUB_SERVER_URL`| The URL of the {% data variables.product.product_name %} server. For example: `https://{% data variables.product.product_url %}`. | `GITHUB_SHA` | The commit SHA that triggered the workflow. The value of this commit SHA depends on the event that triggered the workflow. For more information, see [Events that trigger workflows](/actions/using-workflows/events-that-trigger-workflows). For example, `ffac537e6cbbf934b08745a378932722df287a53`. | +{%- if actions-job-summaries %} +| `GITHUB_STEP_SUMMARY` | The path on the runner to the file that contains job summaries from workflow commands. This file is unique to the current step and changes for each step in a job. For example, `/home/rob/runner/_layout/_work/_temp/_runner_file_commands/step_summary_1cb22d7f-5663-41a8-9ffc-13472605c76c`. For more information, see "[Workflow commands for {% data variables.product.prodname_actions %}](/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary)." | +{%- endif %} | `GITHUB_WORKFLOW` | The name of the workflow. For example, `My test workflow`. If the workflow file doesn't specify a `name`, the value of this variable is the full path of the workflow file in the repository. | | `GITHUB_WORKSPACE` | The default working directory on the runner for steps, and the default location of your repository when using the [`checkout`](https://github.com/actions/checkout) action. For example, `/home/runner/work/my-repo-name/my-repo-name`. | {%- if actions-runner-arch-envvars %} diff --git a/content/actions/using-workflows/workflow-commands-for-github-actions.md b/content/actions/using-workflows/workflow-commands-for-github-actions.md index ec8355690a..3ce31cf10a 100644 --- a/content/actions/using-workflows/workflow-commands-for-github-actions.md +++ b/content/actions/using-workflows/workflow-commands-for-github-actions.md @@ -110,6 +110,9 @@ The following table shows which toolkit functions are available within a workflo | `core.getInput` | Accessible using environment variable `INPUT_{NAME}` | | `core.getState` | Accessible using environment variable `STATE_{NAME}` | | `core.isDebug` | Accessible using environment variable `RUNNER_DEBUG` | +{%- if actions-job-summaries %} +| `core.summary` | Accessible using environment variable `GITHUB_STEP_SUMMARY` | +{%- endif %} | `core.saveState` | `save-state` | | `core.setCommandEcho` | `echo` | | `core.setFailed` | Used as a shortcut for `::error` and `exit 1` | @@ -562,14 +565,16 @@ echo "{environment_variable_name}={value}" >> $GITHUB_ENV {% powershell %} - Using PowerShell version 6 and higher: -```pwsh{:copy} -"{environment_variable_name}={value}" >> $env:GITHUB_ENV -``` + + ```pwsh{:copy} + "{environment_variable_name}={value}" >> $env:GITHUB_ENV + ``` - Using PowerShell version 5.1 and below: -```powershell{:copy} -"{environment_variable_name}={value}" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append -``` + + ```powershell{:copy} + "{environment_variable_name}={value}" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append + ``` {% endpowershell %} @@ -656,6 +661,150 @@ steps: {% endpowershell %} +{% if actions-job-summaries %} + +## Adding a job summary + +{% bash %} + +```bash{:copy} +echo "{markdown content}" >> $GITHUB_STEP_SUMMARY +``` + +{% endbash %} + +{% powershell %} + +```pwsh{:copy} +"{markdown content}" >> $env:GITHUB_STEP_SUMMARY +``` + +{% endpowershell %} + +You can set some custom Markdown for each job so that it will be displayed on the summary page of a workflow run. You can use job summaries to display and group unique content, such as test result summaries, so that someone viewing the result of a workflow run doesn't need to go into the logs to see important information related to the run, such as failures. + +Job summaries support [{% data variables.product.prodname_dotcom %} flavored Markdown](https://github.github.com/gfm/), and you can add your Markdown content for a step to the `GITHUB_STEP_SUMMARY` environment file. `GITHUB_STEP_SUMMARY` is unique for each step in a job. For more information about the per-step file that `GITHUB_STEP_SUMMARY` references, see "[Environment files](#environment-files)." + +When a job finishes, the summaries for all steps in a job are grouped together into a single job summary and are shown on the workflow run summary page. If multiple jobs generate summaries, the job summaries are ordered by job completion time. + +### Example + +{% bash %} + +```bash{:copy} +echo "### Hello world! :rocket:" >> $GITHUB_STEP_SUMMARY +``` + +{% endbash %} + +{% powershell %} + +```pwsh{:copy} +"### Hello world! :rocket:" >> $env:GITHUB_STEP_SUMMARY +``` + +{% endpowershell %} + +![Markdown summary example](/assets/images/actions-job-summary-simple-example.png) + +### Multiline Markdown content + +For multiline Markdown content, you can use `>>` to continuously append content for the current step. With every append operation, a newline character is automatically added. + +#### Example + +{% bash %} + +```yaml +- name: Generate list using Markdown + run: | + echo "This is the lead in sentence for the list" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY # this is a blank line + echo "- Lets add a bullet point" >> $GITHUB_STEP_SUMMARY + echo "- Lets add a second bullet point" >> $GITHUB_STEP_SUMMARY + echo "- How about a third one?" >> $GITHUB_STEP_SUMMARY +``` + +{% endbash %} + +{% powershell %} + +```yaml +- name: Generate list using Markdown + run: | + "This is the lead in sentence for the list" >> $env:GITHUB_STEP_SUMMARY + "" >> $env:GITHUB_STEP_SUMMARY # this is a blank line + "- Lets add a bullet point" >> $env:GITHUB_STEP_SUMMARY + "- Lets add a second bullet point" >> $env:GITHUB_STEP_SUMMARY + "- How about a third one?" >> $env:GITHUB_STEP_SUMMARY +``` + +{% endpowershell %} + +### Overwriting job summaries + +To clear all content for the current step, you can use `>` to overwrite any previously added content. + +#### Example + +{% bash %} + +```yaml +- name: Overwrite Markdown + run: | + echo "Adding some Markdown content" >> $GITHUB_STEP_SUMMARY + echo "There was an error, we need to clear the previous Markdown with some new content." > $GITHUB_STEP_SUMMARY +``` + +{% endbash %} + +{% powershell %} + +```yaml +- name: Overwrite Markdown + run: | + "Adding some Markdown content" >> $env:GITHUB_STEP_SUMMARY + "There was an error, we need to clear the previous Markdown with some new content." > $env:GITHUB_STEP_SUMMARY +``` + +{% endpowershell %} + +### Removing job summaries + +To completely remove a summary for the current step, the file that `GITHUB_STEP_SUMMARY` references can be deleted. + +#### Example + +{% bash %} + +```yaml +- name: Delete all summary content + run: | + echo "Adding Markdown content that we want to remove before the step ends" >> $GITHUB_STEP_SUMMARY + rm $GITHUB_STEP_SUMMARY +``` + +{% endbash %} + +{% powershell %} + +```yaml +- name: Delete all summary content + run: | + "Adding Markdown content that we want to remove before the step ends" >> $env:GITHUB_STEP_SUMMARY + rm $env:GITHUB_STEP_SUMMARY +``` + +{% endpowershell %} + +After a step has completed, job summaries are uploaded and subsequent steps cannot modify previously uploaded Markdown content. Summaries automatically mask any secrets that might have been added accidentally. If a job summary contains sensitive information that must be deleted, you can delete the entire workflow run to remove all its job summaries. For more information see "[Deleting a workflow run](/actions/managing-workflow-runs/deleting-a-workflow-run)." + +### Step isolation and limits + +Job summaries are isolated between steps and each step is restricted to a maximum size of 1MiB. Isolation is enforced between steps so that potentially malformed Markdown from a single step cannot break Markdown rendering for subsequent steps. If more than 1MiB of content is added for a step, then the upload for the step will fail and an error annotation will be created. Upload failures for job summaries do not affect the overall status of a step or a job. A maximum of 20 job summaries from steps are displayed per job. + +{% endif %} + ## Adding a system path Prepends a directory to the system `PATH` variable and automatically makes it available to all subsequent actions in the current job; the currently running action cannot access the updated path variable. To see the currently defined paths for your job, you can use `echo "$PATH"` in a step or an action. @@ -677,21 +826,20 @@ echo "{path}" >> $GITHUB_PATH ### Example -This example demonstrates how to add the user `$HOME/.local/bin` directory to `PATH`: - {% bash %} +This example demonstrates how to add the user `$HOME/.local/bin` directory to `PATH`: + ```bash{:copy} echo "$HOME/.local/bin" >> $GITHUB_PATH ``` {% endbash %} +{% powershell %} This example demonstrates how to add the user `$env:HOMEPATH/.local/bin` directory to `PATH`: -{% powershell %} - ```pwsh{:copy} "$env:HOMEPATH/.local/bin" >> $env:GITHUB_PATH ``` diff --git a/data/features/actions-job-summaries.yml b/data/features/actions-job-summaries.yml new file mode 100644 index 0000000000..b1da5052e0 --- /dev/null +++ b/data/features/actions-job-summaries.yml @@ -0,0 +1,7 @@ +# Reference: #6405 +# Documentation for job summaries for jobs on the workflow run summary page. +versions: + fpt: '*' + ghec: '*' + ghes: '>3.5' + ghae: 'issue-6405' diff --git a/data/reusables/repositories/view-run.md b/data/reusables/repositories/view-run.md index d9a10ee0d9..d9ad77c666 100644 --- a/data/reusables/repositories/view-run.md +++ b/data/reusables/repositories/view-run.md @@ -1,2 +1,3 @@ -1. From the list of workflow runs, click the name of the run you want to see. -![Name of workflow run](/assets/images/help/repository/superlinter-run-name.png) +1. From the list of workflow runs, click the name of the run to see the workflow run summary. + + ![Name of workflow run](/assets/images/help/repository/run-name.png)