Composite Actions Doc release (#20738)

content/actions/creating-actions/about-actions.md

@@ -39,7 +39,7 @@ You can build Docker container and JavaScript actions. Actions require a metadat
 | ---- | ------------------- |
 | Docker container | Linux |
 | JavaScript | Linux, macOS, Windows |
-| Composite run steps | Linux, macOS, Windows |
+| Composite Actions | Linux, macOS, Windows |
 
 ### Docker container actions
 
@@ -57,9 +57,9 @@ JavaScript actions can run directly on a runner machine, and separate the action
 
 If you're developing a Node.js project, the {% data variables.product.prodname_actions %} Toolkit provides packages that you can use in your project to speed up development. For more information, see the [actions/toolkit](https://github.com/actions/toolkit) repository.
 
-### Composite run steps actions
+### Composite Actions
 
-A _composite run steps_ action allows you to combine multiple workflow run steps within one action. For example, you can use this feature to bundle together multiple run commands into an action, and then have a workflow that executes the bundled commands as a single step using that action. To see an example, check out "[Creating a composite run steps action](/actions/creating-actions/creating-a-composite-run-steps-action)".
+A _composite_ action allows you to combine multiple workflow steps within one action. For example, you can use this feature to bundle together multiple run commands into an action, and then have a workflow that executes the bundled commands as a single step using that action. To see an example, check out "[Creating a composite action](/actions/creating-actions/creating-a-composite-action)".
 
 ## Choosing a location for your action
 

content/actions/creating-actions/creating-a-composite-action.md

@@ -1,7 +1,9 @@
 ---
-title: Creating a composite run steps action
+title: Creating a composite action
-intro: 'In this guide, you''ll learn how to build a composite run steps action.'
+intro: 'In this guide, you''ll learn how to build a composite action.'
 product: '{% data reusables.gated-features.actions %}'
+redirect_from:
+  - /actions/creating-actions/creating-a-composite-run-steps-action
 versions:
   fpt: '*'
   ghes: '*'
@@ -9,7 +11,7 @@ versions:
 type: tutorial
 topics:
   - Action development
-shortTitle: Composite run steps action
+shortTitle: Composite action
 ---
 
 {% data reusables.actions.enterprise-beta %}
@@ -18,9 +20,9 @@ shortTitle: Composite run steps action
 
 ## Introduction
 
-In this guide, you'll learn about the basic components needed to create and use a packaged composite run steps action. To focus this guide on the components needed to package the action, the functionality of the action's code is minimal. The action prints "Hello World" and then "Goodbye",  or if you provide a custom name, it prints "Hello [who-to-greet]" and then "Goodbye". The action also maps a random number to the `random-number` output variable, and runs a script named `goodbye.sh`.
+In this guide, you'll learn about the basic components needed to create and use a packaged composite action. To focus this guide on the components needed to package the action, the functionality of the action's code is minimal. The action prints "Hello World" and then "Goodbye",  or if you provide a custom name, it prints "Hello [who-to-greet]" and then "Goodbye". The action also maps a random number to the `random-number` output variable, and runs a script named `goodbye.sh`.
 
-Once you complete this project, you should understand how to build your own composite run steps action and test it in a workflow.
+Once you complete this project, you should understand how to build your own composite action and test it in a workflow.
 
 {% data reusables.github-actions.context-injection-warning %}
 
@@ -28,17 +30,17 @@ Once you complete this project, you should understand how to build your own comp
 
 Before you begin, you'll create a {% data variables.product.product_name %} repository.
 
-1. Create a new public repository on {% data variables.product.product_location %}. You can choose any repository name, or use the following `hello-world-composite-run-steps-action` example. You can add these files after your project has been pushed to {% data variables.product.product_name %}. For more information, see "[Create a new repository](/articles/creating-a-new-repository)."
+1. Create a new public repository on {% data variables.product.product_location %}. You can choose any repository name, or use the following `hello-world-composite-action` example. You can add these files after your project has been pushed to {% data variables.product.product_name %}. For more information, see "[Create a new repository](/articles/creating-a-new-repository)."
 
 1. Clone your repository to your computer. For more information, see "[Cloning a repository](/articles/cloning-a-repository)."
 
 1. From your terminal, change directories into your new repository.
 
   ```shell
-  cd hello-world-composite-run-steps-action
+  cd hello-world-composite-action
   ```
 
-2. In the `hello-world-composite-run-steps-action` repository, create a new file called `goodbye.sh`, and add the following example code:
+2. In the `hello-world-composite-action` repository, create a new file called `goodbye.sh`, and add the following example code:
 
   ```bash
   echo "Goodbye"
@@ -59,7 +61,7 @@ Before you begin, you'll create a {% data variables.product.product_name %} repo
 
 ## Creating an action metadata file
 
-1. In the `hello-world-composite-run-steps-action` repository, create a new file called `action.yml` and add the following example code. For more information about this syntax, see "[`runs` for a composite run steps](/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-composite-run-steps-actions)".
+1. In the `hello-world-composite-action` repository, create a new file called `action.yml` and add the following example code. For more information about this syntax, see "[`runs` for a composite actions](/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-composite-actions)".
 
     {% raw %}
     **action.yml**
@@ -87,9 +89,9 @@ Before you begin, you'll create a {% data variables.product.product_name %} repo
           shell: bash
     ```
     {% endraw %}
-  This file defines the `who-to-greet` input, maps the random generated number to the `random-number` output variable, and runs the `goodbye.sh` script. It also tells the runner how to execute the composite run steps action.
+  This file defines the `who-to-greet` input, maps the random generated number to the `random-number` output variable, and runs the `goodbye.sh` script. It also tells the runner how to execute the composite action.
 
-  For more information about managing outputs, see "[`outputs` for a composite run steps](/actions/creating-actions/metadata-syntax-for-github-actions#outputs-for-composite-run-steps-actions)".
+  For more information about managing outputs, see "[`outputs` for a composite action](/actions/creating-actions/metadata-syntax-for-github-actions#outputs-for-composite-actions)".
 
   For more information about how to use `github.action_path`, see "[`github context`](/actions/reference/context-and-expression-syntax-for-github-actions#github-context)".
 
@@ -110,9 +112,9 @@ Before you begin, you'll create a {% data variables.product.product_name %} repo
 
 ## Testing out your action in a workflow
 
-The following workflow code uses the completed hello world action that you made in "[Creating an action metadata file](/actions/creating-actions/creating-a-composite-run-steps-action#creating-an-action-metadata-file)".
+The following workflow code uses the completed hello world action that you made in "[Creating an action metadata file](/actions/creating-actions/creating-a-composite-action#creating-an-action-metadata-file)".
 
-Copy the workflow code into a `.github/workflows/main.yml` file in another repository, but replace `actions/hello-world-composite-run-steps-action@v1` with the repository and tag you created. You can also replace the `who-to-greet` input with your name.
+Copy the workflow code into a `.github/workflows/main.yml` file in another repository, but replace `actions/hello-world-composite-action@v1` with the repository and tag you created. You can also replace the `who-to-greet` input with your name.
 
 {% raw %}
 **.github/workflows/main.yml**
@@ -126,7 +128,7 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - id: foo
-        uses: actions/hello-world-composite-run-steps-action@v1
+        uses: actions/hello-world-composite-action@v1
         with:
           who-to-greet: 'Mona the Octocat'
       - run: echo random-number ${{ steps.foo.outputs.random-number }}

content/actions/creating-actions/index.md

@@ -15,7 +15,7 @@ children:
   - /about-actions
   - /creating-a-docker-container-action
   - /creating-a-javascript-action
-  - /creating-a-composite-run-steps-action
+  - /creating-a-composite-action
   - /metadata-syntax-for-github-actions
   - /dockerfile-support-for-github-actions
   - /setting-exit-codes-for-actions

content/actions/creating-actions/metadata-syntax-for-github-actions.md

@@ -58,7 +58,7 @@ inputs:
 
 When you specify an input in a workflow file or use a default input value, {% data variables.product.prodname_dotcom %} creates an environment variable for the input with the name `INPUT_<VARIABLE_NAME>`. The environment variable created converts input names to uppercase letters and replaces spaces with `_` characters.
 
-If the action is written using a [composite](/actions/creating-actions/creating-a-composite-run-steps-action), then it will not automatically get `INPUT_<VARIABLE_NAME>`. If the conversion doesn't occur, you can change these inputs manually. 
+If the action is written using a [composite](/actions/creating-actions/creating-a-composite-action), then it will not automatically get `INPUT_<VARIABLE_NAME>`. If the conversion doesn't occur, you can change these inputs manually. 
 
 To access the environment variable in a Docker container action, you must pass the input using the `args` keyword in the action metadata file. For more information about the action metadata file for Docker container actions, see "[Creating a Docker container action](/articles/creating-a-docker-container-action#creating-an-action-metadata-file)."
 
@@ -106,7 +106,7 @@ outputs:
 
 **Required** A `string` description of the output parameter.
 
-## `outputs` for composite run steps actions
+## `outputs` for composite actions
 
 **Optional** `outputs` use the same parameters as `outputs.<output_id>` and `outputs.<output_id>.description` (see "[`outputs` for {% data variables.product.prodname_actions %}](/actions/creating-actions/metadata-syntax-for-github-actions#outputs)"), but also includes the `value` token.
 
@@ -205,21 +205,29 @@ For example, this `cleanup.js` will only run on Linux-based runners:
   post-if: runner.os == 'linux'
 ```
 
-## `runs` for composite run steps actions
+## `runs` for composite actions
 
 **Required** Configures the path to the composite action, and the application used to execute the code.
 
 ### `runs.using`
 
-**Required** To use a composite run steps action, set this to `"composite"`.
+**Required** To use a composite action, set this to `"composite"`.
 
 ### `runs.steps`
 
-**Required** The run steps that you plan to run in this action.
+{% ifversion fpt or ghes > 3.2 or ghae-issue-4853 %}
+**Required** The steps that you plan to run in this action. These can be either `run` steps or `uses` steps.
+{% else %}
+**Required** The steps that you plan to run in this action.
+{% endif %}
 
 #### `runs.steps[*].run`
 
+{% ifversion fpt or ghes > 3.2 or ghae-issue-4853 %}
+**Optional** The command you want to run. This can be inline or a script in your action repository:
+{% else %}
 **Required** The command you want to run. This can be inline or a script in your action repository:
+{% endif %}
 
 {% raw %}
 ```yaml
@@ -245,11 +253,15 @@ For more information, see "[`github context`](/actions/reference/context-and-exp
 
 #### `runs.steps[*].shell`
 
-**Required** The shell where you want to run the command. You can use any of the shells listed [here](/actions/reference/workflow-syntax-for-github-actions#using-a-specific-shell).
+{% ifversion fpt or ghes > 3.2 or ghae-issue-4853 %}
+**Optional** The shell where you want to run the command. You can use any of the shells listed [here](/actions/reference/workflow-syntax-for-github-actions#using-a-specific-shell). Required if `run` is set.
+{% else %}
+**Required** The shell where you want to run the command. You can use any of the shells listed [here](/actions/reference/workflow-syntax-for-github-actions#using-a-specific-shell). Required if `run` is set.
+{% endif %}
 
 #### `runs.steps[*].name`
 
-**Optional** The name of the composite run step.
+**Optional** The name of the composite step.
 
 #### `runs.steps[*].id`
 
@@ -257,12 +269,63 @@ For more information, see "[`github context`](/actions/reference/context-and-exp
 
 #### `runs.steps[*].env`
 
-**Optional**  Sets a `map` of environment variables for only that step. If you want to modify the environment variable stored in the workflow, use {% ifversion fpt or ghes > 2.22 or ghae %}`echo "{name}={value}" >> $GITHUB_ENV`{% else %}`echo "::set-env name={name}::{value}"`{% endif %} in a composite run step.
+**Optional**  Sets a `map` of environment variables for only that step. If you want to modify the environment variable stored in the workflow, use {% ifversion fpt or ghes > 2.22 or ghae %}`echo "{name}={value}" >> $GITHUB_ENV`{% else %}`echo "::set-env name={name}::{value}"`{% endif %} in a composite step.
 
 #### `runs.steps[*].working-directory`
 
 **Optional**  Specifies the working directory where the command is run.
 
+{% ifversion fpt or ghes > 3.2 or ghae-issue-4853 %}
+#### `runs.steps[*].uses`
+
+**Optional**  Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a [published Docker container image](https://hub.docker.com/).
+
+We strongly recommend that you include the version of the action you are using by specifying a Git ref, SHA, or Docker tag number. If you don't specify a version, it could break your workflows or cause unexpected behavior when the action owner publishes an update.
+- Using the commit SHA of a released action version is the safest for stability and security.
+- Using the specific major action version allows you to receive critical fixes and security patches while still maintaining compatibility. It also assures that your workflow should still work.
+- Using the default branch of an action may be convenient, but if someone releases a new major version with a breaking change, your workflow could break.
+
+Some actions require inputs that you must set using the [`with`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepswith) keyword. Review the action's README file to determine the inputs required.
+
+```yaml
+runs:
+  using: "composite"
+  steps:
+    # Reference a specific commit
+    - uses: actions/checkout@a81bbbf8298c0fa03ea29cdc473d45769f953675
+    # Reference the major version of a release
+    - uses: actions/checkout@v2
+    # Reference a specific version
+    - uses: actions/checkout@v2.2.0
+    # Reference a branch
+    - uses: actions/checkout@main
+    # References a subdirectory in a public GitHub repository at a specific branch, ref, or SHA
+    - uses: actions/aws/ec2@main
+    # References a local action
+    - uses: ./.github/actions/my-action
+    # References a docker public registry action
+    - uses: docker://gcr.io/cloud-builders/gradle
+    # Reference a docker image published on docker hub
+    - uses: docker://alpine:3.8
+```
+
+#### `runs.steps[*].with`
+
+**Optional**  A `map` of the input parameters defined by the action. Each input parameter is a key/value pair.  Input parameters are set as environment variables. The variable is prefixed with INPUT_ and converted to upper case.
+
+```yaml
+runs:
+  using: "composite"
+  steps:
+    - name: My first step
+      uses: actions/hello_world@main
+      with:
+        first_name: Mona
+        middle_name: The
+        last_name: Octocat  
+```
+{% endif %}
+
 ## `runs` for Docker actions
 
 **Required** Configures the image used for the Docker action.

content/actions/guides/index.md

@@ -59,7 +59,7 @@ includeGuides:
   - /actions/learn-github-actions/security-hardening-for-github-actions
   - /actions/creating-actions/about-actions
   - /actions/creating-actions/creating-a-javascript-action
-  - /actions/creating-actions/creating-a-composite-run-steps-action
+  - /actions/creating-actions/creating-a-composite-action
   - /actions/learn-github-actions/migrating-from-azure-pipelines-to-github-actions
   - /actions/learn-github-actions/migrating-from-circleci-to-github-actions
   - /actions/learn-github-actions/migrating-from-gitlab-cicd-to-github-actions

content/actions/learn-github-actions/security-hardening-for-github-actions.md

@@ -58,7 +58,7 @@ For more information, see "[About code owners](/github/creating-cloning-and-arch
 
 ## Understanding the risk of script injections
 
-When creating workflows, [custom actions](/actions/creating-actions/about-actions), and [composite run step](/actions/creating-actions/creating-a-composite-run-steps-action) actions, you should always consider whether your code might execute untrusted input from attackers. This can occur when an attacker adds malicious commands and scripts to a context. When your workflow runs, those strings might be interpreted as code which is then executed on the runner.
+When creating workflows, [custom actions](/actions/creating-actions/about-actions), and [composite actions](/actions/creating-actions/creating-a-composite-action) actions, you should always consider whether your code might execute untrusted input from attackers. This can occur when an attacker adds malicious commands and scripts to a context. When your workflow runs, those strings might be interpreted as code which is then executed on the runner.
 
  Attackers can add their own malicious content to the [`github` context](/actions/reference/context-and-expression-syntax-for-github-actions#github-context), which should be treated as potentially untrusted input. These contexts typically end with `body`, `default_branch`, `email`, `head_ref`, `label`, `message`, `name`, `page_name`,`ref`, and `title`.  For example: `github.event.issue.title`, or `github.event.pull_request.body`. 
  

content/actions/reference/context-and-expression-syntax-for-github-actions.md

@@ -95,7 +95,7 @@ The `github` context contains information about the workflow run and the event t
 |---------------|------|-------------|
 | `github` | `object` | The top-level context available during any job or step in a workflow. |
 | `github.action` | `string` | The name of the action currently running. {% data variables.product.prodname_dotcom %} removes special characters or uses the name `run` when the current step runs a script.  If you use the same action more than once in the same job, the name will include a suffix with the sequence number.  For example, the first script you run will have the name `run1`, and the second script will be named `run2`. Similarly, the second invocation of `actions/checkout` will be `actionscheckout2`. |
-| `github.action_path` | `string` | The path where your action is located. You can use this path to easily access files located in the same repository as your action. This attribute is only supported in composite run steps actions. |
+| `github.action_path` | `string` | The path where your action is located. You can use this path to easily access files located in the same repository as your action. This attribute is only supported in composite actions. |
 | `github.actor` | `string` | The login of the user that initiated the workflow run. |
 | `github.base_ref` | `string` | The `base_ref` or target branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is either `pull_request` or `pull_request_target`. |
 | `github.event` | `object` | The full event webhook payload. For more information, see "[Events that trigger workflows](/articles/events-that-trigger-workflows/)." You can access individual properties of the event using this context. |

content/actions/reference/environment-variables.md

@@ -58,7 +58,7 @@ We strongly recommend that actions use environment variables to access the files
 | `GITHUB_RUN_NUMBER` | {% data reusables.github-actions.run_number_description %} |
 | `GITHUB_JOB` | The [job_id](/actions/reference/workflow-syntax-for-github-actions#jobsjob_id) of the current job. |
 | `GITHUB_ACTION` | The unique identifier (`id`) of the action. |
-| `GITHUB_ACTION_PATH` | The path where your action is located. You can use this path to access files located in the same repository as your action. This variable is only supported in composite run steps actions. |
+| `GITHUB_ACTION_PATH` | The path where your action is located. You can use this path to access files located in the same repository as your action. This variable is only supported in composite actions. |
 | `GITHUB_ACTIONS` | Always set to `true` when {% data variables.product.prodname_actions %} is running the workflow. You can use this variable to differentiate when tests are being run locally or by {% data variables.product.prodname_actions %}.
 | `GITHUB_ACTOR` | The name of the person or app that initiated the workflow. For example, `octocat`. |
 | `GITHUB_REPOSITORY` | The owner and repository name. For example, `octocat/Hello-World`. |

data/learning-tracks/actions.yml

@@ -57,7 +57,7 @@ create_actions:
     - /actions/creating-actions/about-actions
     - /actions/creating-actions/creating-a-docker-container-action
     - /actions/creating-actions/creating-a-javascript-action
-    - /actions/creating-actions/creating-a-composite-run-steps-action
+    - /actions/creating-actions/creating-a-composite-action
     - /actions/creating-actions/metadata-syntax-for-github-actions
     - /actions/creating-actions/dockerfile-support-for-github-actions
     - /actions/creating-actions/setting-exit-codes-for-actions