From 2a25196ea8e52ca1290091af7589b986888188d0 Mon Sep 17 00:00:00 2001 From: Luke Tomlinson Date: Fri, 17 Sep 2021 10:19:59 -0400 Subject: [PATCH] Add documentation for notice annotation level and new fields (#21427) --- .../workflow-commands-for-github-actions.md | 70 ++++++++++++++----- .../actions/message-annotation-explanation.md | 1 + data/reusables/actions/message-parameters.md | 8 +++ 3 files changed, 60 insertions(+), 19 deletions(-) create mode 100644 data/reusables/actions/message-annotation-explanation.md create mode 100644 data/reusables/actions/message-parameters.md diff --git a/content/actions/reference/workflow-commands-for-github-actions.md b/content/actions/reference/workflow-commands-for-github-actions.md index dade5fc450..211a0407ac 100644 --- a/content/actions/reference/workflow-commands-for-github-actions.md +++ b/content/actions/reference/workflow-commands-for-github-actions.md @@ -70,14 +70,14 @@ The following table shows which toolkit functions are available within a workflo | Toolkit function | Equivalent workflow command | | ----------------- | ------------- | | `core.addPath` | {% ifversion fpt or ghes > 2.22 or ghae %}Accessible using environment file `GITHUB_PATH`{% else %} `add-path` {% endif %} | -| `core.debug` | `debug` | +| `core.debug` | `debug` |{% ifversion fpt or ghes > 3.2 or ghae-issue-4929 %} +| `core.notice` | `notice` |{% endif %} | `core.error` | `error` | | `core.endGroup` | `endgroup` | | `core.exportVariable` | {% ifversion fpt or ghes > 2.22 or ghae %}Accessible using environment file `GITHUB_ENV`{% else %} `set-env` {% endif %} | | `core.getInput` | Accessible using environment variable `INPUT_{NAME}` | | `core.getState` | Accessible using environment variable `STATE_{NAME}` | | `core.isDebug` | Accessible using environment variable `RUNNER_DEBUG` | -| `core.notice` | `notice` | | `core.saveState` | `save-state` | | `core.setFailed` | Used as a shortcut for `::error` and `exit 1` | | `core.setOutput` | `set-output` | @@ -88,7 +88,9 @@ The following table shows which toolkit functions are available within a workflo {% ifversion ghes < 3.0 %} ## Setting an environment variable -`::set-env name={name}::{value}` +``` +::set-env name={name}::{value} +``` Creates or updates an environment variable for any steps running next in a job. The step that creates or updates the environment variable does not have access to the new value, but all subsequent steps in a job will have access. Environment variables are case-sensitive and you can include punctuation. @@ -101,7 +103,9 @@ echo "::set-env name=action_state::yellow" ## Setting an output parameter -`::set-output name={name}::{value}` +``` +::set-output name={name}::{value} +``` Sets an action's output parameter. @@ -116,7 +120,9 @@ echo "::set-output name=action_fruit::strawberry" {% ifversion ghes < 3.0 %} ## Adding a system path -`::add-path::{path}` +``` +::add-path::{path} +``` Prepends a directory to the system `PATH` variable for all subsequent actions in the current job. The currently running action cannot access the new path variable. @@ -129,7 +135,9 @@ echo "::add-path::/path/to/dir" ## Setting a debug message -`::debug::{message}` +``` +::debug::{message} +``` Prints a debug message to the log. You must create a secret named `ACTIONS_STEP_DEBUG` with the value `true` to see the debug messages set by this command in the log. For more information, see "[Enabling debug logging](/actions/managing-workflow-runs/enabling-debug-logging)." @@ -139,40 +147,56 @@ Prints a debug message to the log. You must create a secret named `ACTIONS_STEP_ echo "::debug::Set the Octocat variable" ``` +{% ifversion fpt or ghes > 3.2 or ghae-issue-4929 %} + ## Setting a notice message -`::notice file={name},line={line},col={col}::{message}` +``` +::notice file={name},line={line},endLine={endLine},title={title}::{message} +``` -Creates a notice message and prints the message to the log. You can optionally provide a filename (`file`), line number (`line`), and column number (`col`) where the notice occurred. Line and column numbers start at 1. +Creates a notice message and prints the message to the log. {% data reusables.actions.message-annotation-explanation %} + +{% data reusables.actions.message-parameters %} ### Example ``` bash -echo "::notice file=app.js,line=1,col=5::Spelling mistake in string" +echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon" ``` +{% endif %} + ## Setting a warning message -`::warning file={name},line={line},col={col}::{message}` +``` +::warning file={name},line={line},endLine={endLine},title={title}::{message} +``` -Creates a warning message and prints the message to the log. You can optionally provide a filename (`file`), line number (`line`), and column number (`col`) where the warning occurred. Line and column numbers start at 1. +Creates a warning message and prints the message to the log. {% data reusables.actions.message-annotation-explanation %} + +{% data reusables.actions.message-parameters %} ### Example ``` bash -echo "::warning file=app.js,line=1,col=5::Missing semicolon" +echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon" ``` ## Setting an error message -`::error file={name},line={line},col={col}::{message}` +``` +::error file={name},line={line},endLine={endLine},title={title}::{message} +``` -Creates an error message and prints the message to the log. You can optionally provide a filename (`file`), line number (`line`), and column number (`col`) where the error occurred. Line and column numbers start at 1. +Creates an error message and prints the message to the log. {% data reusables.actions.message-annotation-explanation %} + +{% data reusables.actions.message-parameters %} ### Example ``` bash -echo "::error file=app.js,line=10,col=15::Something went wrong" +echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon" ``` ## Grouping log lines @@ -196,7 +220,9 @@ echo "::endgroup::" ## Masking a value in log -`::add-mask::{value}` +``` +::add-mask::{value} +``` Masking a value prevents a string or variable from being printed in the log. Each masked word separated by whitespace is replaced with the `*` character. You can use an environment variable or string for the mask's `value`. @@ -231,7 +257,9 @@ To stop the processing of workflow commands, pass a unique token to `stop-comman {% endwarning %} -`::{endtoken}::` +``` +::{endtoken}:: +``` ### Example stopping and starting workflow commands @@ -291,7 +319,9 @@ steps: ## Setting an environment variable -`echo "{name}={value}" >> $GITHUB_ENV` +``` bash +echo "{name}={value}" >> $GITHUB_ENV +``` Creates or updates an environment variable for any steps running next in a job. The step that creates or updates the environment variable does not have access to the new value, but all subsequent steps in a job will have access. Environment variables are case-sensitive and you can include punctuation. @@ -336,7 +366,9 @@ steps: ## Adding a system path -`echo "{path}" >> $GITHUB_PATH` +``` bash +echo "{path}" >> $GITHUB_PATH +``` Prepends a directory to the system `PATH` variable and 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. diff --git a/data/reusables/actions/message-annotation-explanation.md b/data/reusables/actions/message-annotation-explanation.md new file mode 100644 index 0000000000..fab91b5275 --- /dev/null +++ b/data/reusables/actions/message-annotation-explanation.md @@ -0,0 +1 @@ +This message will create an annotation, which can associate the message with a particular file in your repository. Optionally, your message can specify a position within the file. diff --git a/data/reusables/actions/message-parameters.md b/data/reusables/actions/message-parameters.md new file mode 100644 index 0000000000..f5f9473c4d --- /dev/null +++ b/data/reusables/actions/message-parameters.md @@ -0,0 +1,8 @@ +| Parameter | Value | +| :- | :- |{% ifversion fpt or ghes > 3.2 or ghae-issue-4929 %} +| `title` | Custom title |{% endif %} +| `file` | Filename | +| `col` | Column number, starting at 1 |{% ifversion fpt or ghes > 3.2 or ghae-issue-4929 %} +| `endColumn` | End column number |{% endif %} +| `line` | Line number, starting at 1 |{% ifversion fpt or ghes > 3.2 or ghae-issue-4929 %} +| `endLine` | End line number |{% endif %}