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/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-for-your-schoolwork/about-github-education-for-students.md b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-for-your-schoolwork/about-github-education-for-students.md index 1ecdc9fecf..f555621385 100644 --- a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-for-your-schoolwork/about-github-education-for-students.md +++ b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-for-your-schoolwork/about-github-education-for-students.md @@ -10,11 +10,11 @@ versions: fpt: '*' shortTitle: For students --- -Using {% data variables.product.prodname_dotcom %} for your school projects is a practical way to collaborate with others and build a portfolio that showcases real-world experience. - {% data reusables.education.about-github-education-link %} -Everyone with a {% data variables.product.prodname_dotcom %} account can collaborate in unlimited public and private repositories with {% data variables.product.prodname_free_user %}. As a student, you can also apply for GitHub Student benefits, which includes access to GitHub Global Campus, a digital campus for our GitHub student community to take advantage of some of the best programs that GitHub Education has to offer. GitHub Global Campus includes the {% data variables.product.prodname_student_pack %}, which offers free access to tools and services used by professional developers, as well as access to [Campus TV](https://www.twitch.tv/githubeducation) content, student events, GitHub Classroom Assignments, and much more, to help students with their technical career goals. For more information, see "[Apply for a student developer pack](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/apply-for-a-student-developer-pack)" and [{% data variables.product.prodname_education %}](https://education.github.com/). +Using {% data variables.product.prodname_dotcom %} for your school projects is a practical way to collaborate with others and build a portfolio that showcases real-world experience. + +Everyone with a {% data variables.product.prodname_dotcom %} account can collaborate in unlimited public and private repositories with {% data variables.product.prodname_free_user %}. As a student, you can also apply for GitHub Student benefits. For more information, see "[Apply for a student developer pack](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/apply-for-a-student-developer-pack)" and [{% data variables.product.prodname_education %}](https://education.github.com/). If you're a member of a FIRST robotics club, your mentor can apply for an educator discount so your team can collaborate using {% data variables.product.prodname_team %}, which allows unlimited users and private repositories, for free. For more information, see "[Apply for an educator or researcher discount](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/apply-for-an-educator-or-researcher-discount)." 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/education/about-github-education-link.md b/data/reusables/education/about-github-education-link.md index 4106c559a9..bb401189e9 100644 --- a/data/reusables/education/about-github-education-link.md +++ b/data/reusables/education/about-github-education-link.md @@ -1 +1,3 @@ +As a student or faculty member at an accredited educational institution, you can apply for GitHub Education benefits, which includes access to GitHub Global Campus. Global Campus is a portal that allows the GitHub Education Community to access their education benefits—all in one place! The Global Campus portal includes access to the GitHub Education Community, industry tools used by professional developers, events, [Campus TV](https://www.twitch.tv/githubeducation) content, GitHub Classroom, and other exclusive features to help students and teachers shape the next generation of software development. + Before applying for an individual discount, check if your learning community is already partnered with us as a {% data variables.product.prodname_campus_program %} school. For more information, see "[About {% data variables.product.prodname_campus_program %}](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/about-github-campus-program)." 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)