Add optional parameters `ref` and `sha`

[elliot-nelson]

SUMMARY

Add two optional parameters to the task:

• ref:, which will override the default GITHUB_REF value
• sha:, which will override the default GITHUB_SHA value

DETAILS

Allowing the user to specify exactly what branch name and commit SHA to pass to the Azure pipeline is necessary for workflows that trigger from non-pull-request events like issue_comment. For security reasons, it's impossible to override the values of GITHUB_REF and GITHUB_SHA in the environment, which means for these workflows these values will always be pointing at the current tip of the default branch (e.g. main/master). That makes it impossible to trigger an Azure pipeline pointing at the current head branch of a pull request from an issue comment.

By supporting these optional parameters, we can allow the workflow to use an inline github script or other avenue to retrieve the desired ref/sha from the event pull request, and then pass them to the Azure pipeline.

An example of what that might look like:

on: issue_comment
jobs:
  pr_command:
    name: PR Command
    if: github.event.issue.pull_request
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v3
        id: get-pr
        with:
          script: |
            const request = {
              owner: context.repo.owner,
              repo: context.repo.repo,
              pull_number: context.issue.number
            };
            core.info(`Getting PR #${request.pull_number} from ${request.owner}/${request.repo}`);
            try {
              const result = await github.pulls.get(request);
              return result.data;
            } catch (err) {
              core.setFailed(`Request failed with error ${err}`);
            }
      - name: 'Trigger pipeline'
        uses: Azure/pipelines@v1
        with:
          azure-devops-project-url: https://dev.azure.com/ORG/PROJECT
          azure-pipeline-name: my-issue-comment-pipeline
          azure-devops-token: ${{ secrets.AZURE_DEVOPS_TOKEN }}
          ref: ${{ fromJSON(steps.get-pr.outputs.result).head.ref }}
          sha: ${{ fromJSON(steps.get-pr.outputs.result).head.sha }}

(This example based on the excellent comment here: https://github.com/actions/checkout/issues/331#issuecomment-707103442)

[ghost]

All CLA requirements met.

[rjulius23]

Hey @elliot-nelson are you planning to push this in ? Or can I take it over? :)

[elliot-nelson]

@rjulius23 I wouldn't mind if you wanted to take it over! Unfortunately my need for the change has passed, as the pipelines we were targeting ended up moving to GitHub Actions.