make reference accessible in reusable workflow

Nobody has claimed this yet.

Describe the enhancement

A reusable workflow should be able to access the reference that it was called for.

Context

A reusable workflow in public repos may be called by appending a reference which can be a SHA, a release tag, or a branch name, as for example:
{owner}/{repo}/.github/workflows/{filename}@{ref}

Githubs documentation states:

When a reusable workflow is triggered by a caller workflow, the github context is always associated with the caller workflow.

The problem

Since the github context is always associated with the caller workflow, the reusable workflow cannot access the reference, for example the tag v1.0.0. However, knowing the reference is important when the reusable workflow needs to checkout the repository in order to make use of composite actions.

Code snippet

Assume that the caller workflow is being executed from within the main branch and calls the ref v1.0.0. of a reusable workflow:

name: Caller workflow
on:
  workflow_dispatch:

jobs:
  caller:
    uses: owner/public-repo/.github/workflows/reusable-workflow.yml@v1.0.0

Here is the reusable workflow that uses a composite action:

name: reusable workflows
on:
  workflow_call:

jobs:
  first-job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3.1.0
        with:
          repository: owner/public-repo
          ref: ${{ github.ref_name }}

      - name: composite action
        uses: ./actions/my-composite-action

In the above code snippet, ${{ github.ref_name }} is main instead of v1.0.0 because github context is always associated with the caller workflow. Therefore, the composite actions code is based on main and not on v1.0.0.

Proposal

Introduce a new github context variable caller_ref which reflects the reference indicated by the caller.
The reusable workflow could then use it as follows:

name: reusable workflows
on:
  workflow_call:

jobs:
  first-job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3.1.0
        with:
          repository: owner/public-repo
          ref: ${{ github.caller_ref }}

      - name: composite action
        uses: ./actions/my-composite-action

Or even shorter without the need to checkout:

name: reusable workflows
on:
  workflow_call:

jobs:
  first-job:
    runs-on: ubuntu-latest
    steps:
      - name: composite action
        uses: ./actions/my-composite-action@${{ github.caller_ref }}

Now, the composite action would be using v1.0.0. as indicated by the caller.

Related to this FR:

No implementation files, tests, or entry points are named. Start by reviewing the reusable-workflow examples and the related toolkit issue; the work is done when a reusable workflow can access the caller-selected SHA, tag, or branch reference as proposed.

Written by the indexing model from the issue text.

Description

Contributor guide

First steps

Research direction

Assessment