Pull request description variable interpolation

[AndersDJohnson]

Hello! 👋 Apologies if this has been requested before, and I'm not aware!

Problem:

Users of GitHub often integrate with several external tools during the pull request lifecycle. These tools need to know some metadata about the PRs, like their number. Often that metadata can be provided to the tools via their URL, e.g., https://example.com/my-external-tool/my-org/my-repo/123.

We often want to include these links in PR descriptions, alongside testing instructions, etc., for reviewers to reference.

In advanced setups, we can have bots post status checks or comments with relevant links, or even update PR descriptions themselves (at risk of conflicting with manual edits from authors). But that's not always easy or possible for some tools or teams or projects. Comments particularly can get buried on a PR with a lot of activity over time (though some solution to submit pinned comments could help).

Solution?

What if we were able to provide links to external tools automatically in PR descriptions through the use of PR templates or saved replies?

The main limitation with doing this in PR templates is that we don't know the PR number upfront. Today teams could create placeholders, but they'd need to be manually replaced with actual PR metadata.

It seems like we could automate this by supporting string interpolation for some well-known variables, similar to environment variables, that GitHub would make available, and process on PR creation or description edit.

For example, if we're working with a PR #123 on repo my-org/my-repo with the following description body contents:

Please check external tool: https://example.com/my-external-tool/my-org/my-repo/${PULL_NUMBER}

would automatically have that description rewritten to (or at least visually render as):

Please check external tool: https://example.com/my-external-tool/my-org/my-repo/123

with the placeholder ${PULL_NUMBER} replaced with the actual PR number.

Possible variables might include:

• PULL_NUMBER
• PULL_HTML_URL
• PULL_HTML_PATH
• PULL_AUTHOR
• PULL_REPO
• PULL_ORG / PULL_OWNER
• PULL_BRANCH (suggestion from @MustafaHaddara below)
• etc.

Or, we could even go further and offer access to much of the Pull schema in the GraphQL API directly, e.g., pull.number, etc.

The interpolation syntax is not too important here and could be changed.

In case this new syntax breaks any existing setups, we could make this an opt-in feature per-repo or per-organization - perhaps similar to the existing opt-in feature for autolink references.

Thoughts?

[julien-deramond]

If it can help, here is a use case observed in Bootstrap repository.

In our Pull Request template we have:

#### Live previews

<!-- Please add direct links where your modifications can be seen in the documentation -->

- <https://deploy-preview-{your_pr_number}--twbs-bootstrap.netlify.app/>

All of our PRs automatically deploy a website via Netlify and the generated link to access it contains the PR number. So right now, users have to create the PR, and then click on the Edit button, and then modify this link to add the PR number so that the link actually works. Obviously, almost nobody changes it 😇

It would be very helpful to be have access to these variables to change it to https://deploy-preview-${PULL_NUMBER}--twbs-bootstrap.netlify.app (or another wording) as proposed by this discussion's OP.

[julien-deramond]

To help those encountering this issue, our current approach involves utilizing a .github/workflows/update-pr-desc-links.yml file containing:

name: Update PR Description Netlify Preview URLs
on:
  pull_request_target:
    types:
      - opened

jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Update PR Description
        run: |
          PR_UPDATED_BODY="$(
            gh api /repos/$OWNER/$REPO/pulls/$PR_NUMBER | jq -r '.body' | sed 's/{your_pr_number}/${{ env.PR_NUMBER }}/g'
          )"
          gh api --method PATCH /repos/$OWNER/$REPO/pulls/$PR_NUMBER -f body="$PR_UPDATED_BODY"
        env:
          GITHUB_TOKEN: ${{ secrets.PROJECT_MOD_PERSONAL_TOKEN_CLASSIC }}
          OWNER: ${{ github.repository_owner }}
          REPO: ${{ github.event.repository.name }}
          PR_NUMBER: ${{ github.event.number }}

[MustafaHaddara]

+1 to this, just commenting to say the branch name should be made available as well. My org has a number of internal repos where the structure of our pull request preview branches look very similar to the Bootstrap example above, but use the branch name instead of PR number.

[CaelumNew]

Here's how it could work:

GitHub could support placeholders like ${PULL_NUMBER} or ${PULL_HTML_URL} in PR descriptions.
Users could opt-in to use this feature on a per-repo or per-organization basis.
GitHub could also offer access to PR metadata through the GraphQL API directly.
This way, users could easily include relevant information without manual edits, making the review process smoother.

thoughts?

[sebas-w]

+1 this as well. I was looking for a smoother way to fill out a PR to contain all commits done in the pr via concise list via the template and stumbled on this discussion.

so just commenting to say: I would love to be able to access commits in the pr template via a variable as well.

[sashak007]

+1 it would be great to have the PULL_BRANCH variable populate in the pull request description. My org creates test resources based on the branch name and having those links built into the pull request template would greatly improve documentation and review hand-offs.

[DarkteK]

+1 Woo man, 2 years and still not a single word on this feature?
It could be a really good implementation