Document the $/ self-referencing uses syntax for actions and reusable workflows (#62055)

Co-authored-by: Joe Clark <31087804+jc-clark@users.noreply.github.com>

Author: nodeselector

content/actions/how-tos/write-workflows/choose-what-workflows-do/find-and-customize-actions.md

@@ -66,9 +66,51 @@ An action's listing page includes the action's version and the workflow syntax r
 
 ### Adding an action from the same repository
 
-If an action is defined in the same repository where your workflow file uses the action, you can reference the action with either the ‌`{owner}/{repo}@{ref}` or `./path/to/dir` syntax in your workflow file.
+If an action is defined in the same repository where your workflow file uses the action, you can reference the action with the `$/path/to/dir` self repository reference, or with the `{owner}/{repo}@{ref}` or `./path/to/dir` syntax in your workflow file. The `$/` syntax is not available in {% data variables.product.prodname_ghe_server %}.
+
+Example repository file structure:
+
+```shell
+|-- hello-world (repository)
+|   |__ .github
+|       └── workflows
+|           └── my-first-workflow.yml
+|       └── actions
+|           |__ hello-world-action
+|               └── action.yml
+```
+
+We recommend referencing the action with the `$/path/to/dir` self repository reference. This resolves to the same repository at the running commit, so you do not need to check out the repository first. For more information about how `$/` compares to `{owner}/{repo}@{ref}` and `./`, see [AUTOTITLE](/actions/reference/workflows-and-actions/workflow-syntax#example-using-an-action-in-the-same-repository-as-the-workflow-at-the-running-commit-recommended).
+
+Example workflow file using `$/`:
+
+```yaml
+jobs:
+  my_first_job:
+    runs-on: ubuntu-latest
+    steps:
+      # This step references an action in the same repository at the
+      # running commit. No repository checkout is required.
+      - name: Use hello-world-action
+        uses: $/.github/actions/hello-world-action
+```
+
+You can also reference the action with the relative `./path/to/dir` syntax, but it is more error-prone. The path is relative (`./`) to the default working directory (`github.workspace`, `$GITHUB_WORKSPACE`), so it requires a checkout step, and if the action checks out the repository to a location different than the workflow, the relative path must be updated.
 
-{% data reusables.actions.workflows.section-referencing-an-action-from-the-same-repository %}
+Example workflow file using `./`:
+
+```yaml
+jobs:
+  my_first_job:
+    runs-on: ubuntu-latest
+    steps:
+      # This step checks out a copy of your repository.
+      - name: My first step - check out repository
+        uses: {% data reusables.actions.action-checkout %}
+      # This step references the directory that contains the action.
+      - name: Use local hello-world-action
+        uses: ./.github/actions/hello-world-action
+```
 
 The `action.yml` file is used to provide metadata for the action. Learn about the content of this file in [AUTOTITLE](/actions/reference/workflows-and-actions/metadata-syntax).
 

content/actions/reference/workflows-and-actions/metadata-syntax.md

@@ -339,6 +339,8 @@ runs:
     - 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 an action in the same repository at the running commit
+    - uses: $/.github/actions/my-action
     # References a local action
     - uses: ./.github/actions/my-action
     # References a docker public registry action
@@ -347,6 +349,10 @@ runs:
     - uses: docker://alpine:3.8
 ```
 
+To reference an action stored in the same repository as your composite action, use the `$/` self repository reference, as shown in the `$/.github/actions/my-action` example above. It resolves to that repository at the running commit, so you do not need to check out the repository first, and it must not include an `@{ref}` suffix. The `$/` syntax is not available in {% data variables.product.prodname_ghe_server %}.
+
+For a comparison of `$/`, `{owner}/{repo}@{ref}`, and `./`, see [AUTOTITLE](/actions/reference/workflows-and-actions/workflow-syntax#example-using-an-action-in-the-same-repository-as-the-workflow-at-the-running-commit-recommended).
+
 #### `runs.steps[*].with`
 
 **Optional** A `map` of the input parameters defined by the action. Each input parameter is a key/value pair. For more information, see [Example: Specifying inputs](#example-specifying-inputs).

content/actions/reference/workflows-and-actions/workflow-syntax.md

@@ -597,11 +597,42 @@ jobs:
         uses: actions/aws/ec2@main
 ```
 
+### Example: Using an action in the same repository as the workflow at the running commit (recommended)
+
+`$/path/to/action`
+
+The `$/` prefix is the self repository reference. It references an action stored in the same repository as the workflow or action that is currently running, and resolves to that repository at the running commit (the same SHA as the running workflow or action). You do not need to check out the repository first, so it is the recommended way to reference an action within its own repository.
+
+The `$/` syntax is not available in {% data variables.product.prodname_ghe_server %}.
+
+A `$/` reference must not include an `@{ref}` suffix. The ref is always the commit the running workflow or action is using, so a reference such as `$/actions/my-action@v1` is invalid.
+
+`$/` always resolves against the repository of the file it appears in, not the repository that called it. For example, if a reusable workflow in one repository is called by a workflow in another repository, a `$/` reference in the called workflow resolves to the called workflow's repository, not the calling workflow's repository. This makes `$/` reliable for action composition, where a relative `./` path would instead resolve against whatever is checked out in the caller's workspace. For using `$/` in a composite action's steps, see [AUTOTITLE](/actions/reference/workflows-and-actions/metadata-syntax#runsstepsuses).
+
+The following table compares the ways to reference an action.
+
+| Syntax | Resolves to | Recommended for |
+| ------ | ----------- | --------------- |
+| `$/path/to/action` | The same repository as the running workflow or action, at the running commit | Actions in the same repository |
+| `{owner}/{repo}@{ref}` | The specified repository at the specified ref | Actions in another repository |
+| `./path/to/action` | A path in the runner's checked-out workspace, relative to the default working directory (`{% raw %}${{ github.workspace }}{% endraw %}`) | Edge cases only |
+
+```yaml
+on: [push]
+
+jobs:
+  my_first_job:
+    runs-on: ubuntu-latest
+    steps:
+      # References an action in the same repository at the running commit
+      - uses: $/.github/actions/hello-world-action
+```
+
 ### Example: Using an action in the same repository as the workflow
 
 `./path/to/dir`
 
-The path to the directory that contains the action in your workflow's repository. You must check out your repository before using the action.
+The path to the directory that contains the action in your workflow's repository. You must check out your repository before using the action, and the `./` path resolves against the runner's workspace rather than the repository of the running workflow. For most cases, use the `$/` syntax shown above instead.
 
 {% data reusables.actions.workflows.section-referencing-an-action-from-the-same-repository %}
 

data/reusables/actions/allow-specific-actions-intro.md

@@ -3,7 +3,7 @@
 
 ### Allowing select actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} to run
 
-When you choose {% data reusables.actions.policy-label-for-select-actions-workflows %}, local actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} are allowed, and there are additional options for allowing other specific actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %}:
+When you choose {% data reusables.actions.policy-label-for-select-actions-workflows %}, local actions (`./` and `$/`){% ifversion actions-workflow-policy %} and reusable workflows{% endif %} are allowed, and there are additional options for allowing other specific actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %}:
 
 {% data reusables.repositories.settings-permissions-org-policy-note %}
 

data/reusables/actions/reusable-workflow-calling-syntax.md

@@ -1,6 +1,7 @@
+* `$/.github/workflows/{filename}` for a reusable workflow in the same repository. This is the recommended syntax for referencing a reusable workflow in the same repository. This syntax is not available in {% data variables.product.prodname_ghe_server %}.
 * `{owner}/{repo}/.github/workflows/{filename}@{ref}` for reusable workflows in {% ifversion fpt %}public and private{% elsif ghec or ghes %}public, internal and private{% endif %} repositories.
 * `./.github/workflows/{filename}` for reusable workflows in the same repository.
 
-In the first option, `{ref}` can be a SHA, a release tag, or a branch name. If a release tag and a branch have the same name, the release tag takes precedence over the branch name. Using the commit SHA is the safest option for stability and security. For more information, see [AUTOTITLE](/actions/reference/security/secure-use#reusing-third-party-workflows).
+When you reference a reusable workflow with `{owner}/{repo}` and `@{ref}`, the `{ref}` can be a SHA, a release tag, or a branch name. If a release tag and a branch have the same name, the release tag takes precedence over the branch name. Using the commit SHA is the safest option for stability and security. For more information, see [AUTOTITLE](/actions/reference/security/secure-use#reusing-third-party-workflows).
 
-If you use the second syntax option (without `{owner}/{repo}` and `@{ref}`) the called workflow is from the same commit as the caller workflow. Ref prefixes such as `refs/heads` and `refs/tags` are not allowed. You cannot use contexts or expressions in this keyword.
+When you reference a reusable workflow in the same repository using `$/` or `./` (without `{owner}/{repo}` and `@{ref}`), the called workflow is from the same commit as the caller workflow. A `$/` reference must not include an `@{ref}` suffix, and `$/` is not available in {% data variables.product.prodname_ghe_server %}. Ref prefixes such as `refs/heads` and `refs/tags` are not allowed. You cannot use contexts or expressions in this keyword.

data/reusables/actions/uses-keyword-example.md

@@ -4,6 +4,9 @@ jobs:
     uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
   call-workflow-2-in-local-repo:
     uses: ./.github/workflows/workflow-2.yml
+  # The `$/` syntax is not available in GitHub Enterprise Server.
+  call-workflow-in-same-repo-at-running-commit:
+    uses: $/.github/workflows/workflow-2.yml
   call-workflow-in-another-repo:
     uses: octo-org/another-repo/.github/workflows/workflow.yml@v1
 ```