From 88c90c781ae4de8d0c8592cb7b7ac7adf96fe6fb Mon Sep 17 00:00:00 2001 From: robert Date: Tue, 15 Sep 2026 18:05:00 +1000 Subject: [PATCH 1/2] Use pull request safe git_ref and git_commit in GitHub Actions examples On a pull_request event, github.ref is refs/pull//merge and github.sha is the merge commit GitHub creates for the pull request. That commit is not reachable from any branch or tag, so an Octopus release pinned to it can fail to deploy later. Switch the three create-release examples to github.head_ref and github.event.pull_request.head.sha, which fall back to the push values on every other event, and add a note explaining why. Also fix github.event.push.after on the build server plugin page. A push payload exposes the commit as github.event.after, so the old expression was always empty on a push. --- .../build-servers/github-actions.mdx | 22 +++++++++++-------- ...ng-release-from-a-build-server-plug-in.mdx | 6 ++--- 2 files changed, 16 insertions(+), 12 deletions(-) diff --git a/src/pages/docs/packaging-applications/build-servers/github-actions.mdx b/src/pages/docs/packaging-applications/build-servers/github-actions.mdx index e33d3c5fea..dcec0f96b5 100644 --- a/src/pages/docs/packaging-applications/build-servers/github-actions.mdx +++ b/src/pages/docs/packaging-applications/build-servers/github-actions.mdx @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-11-21 +modDate: 2026-09-15 title: GitHub Actions description: Integrating Octopus Deploy into your GitHub Action workflows icon: fa-brands fa-github @@ -79,8 +79,8 @@ jobs: with: project: 'MyProject' release_number: '1.0.0' - git_ref: ${{ github.ref }} - git_commit: ${{ github.sha }} + git_ref: ${{ github.head_ref || github.ref }} + git_commit: ${{ github.event.pull_request.head.sha || github.sha }} # Action to Deploy a Release - name: Deploy a release in Octopus Deploy 🐙 @@ -96,6 +96,10 @@ jobs: Fizz: Buzz ``` +:::div{.hint} +On a pull request, `github.ref` is `refs/pull//merge` and `github.sha` is the merge commit that GitHub creates for the pull request. That commit does not exist on any branch, so a release pinned to it can fail to deploy later. Use `github.head_ref` and `github.event.pull_request.head.sha` instead, as shown above. Both fall back to the push values on every other event. +::: + ### ✍️ Environment variables | Name | Description | @@ -112,8 +116,8 @@ jobs: | `release_number` | The number for the new Release. If omitted, Octopus Deploy will generate a Release number. | | `environments` | A list of Environments in Octopus Deploy in which to run (i.e. Dev, Test, Prod). Add each environment on a new line. | | `variables` | A list of Variables to use in the Deployment in `key: value` format. Add each variable on a new line. | -| `git_ref` | The Git branch from which to source the project code. Required for Projects using version control in Octopus. The example above sources this value from the workflow's [contextual information.](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context) | -| `git_commit` | The Git commit from which to source the project code. Required for Projects using version control in Octopus. The example above sources this value from the workflow's [contextual information.](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context) | +| `git_ref` | The Git branch from which to source the project code. Required for Projects using version control in Octopus. The example above sources this value from the workflow's [contextual information](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context), using `github.head_ref` on pull requests so the release tracks the branch rather than the pull request merge ref. | +| `git_commit` | The Git commit from which to source the project code. Required for Projects using version control in Octopus. The example above sources this value from the workflow's [contextual information](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context), using `github.event.pull_request.head.sha` on pull requests so the release tracks the branch head rather than the merge commit. | | `server` | The base URL hosting Octopus Deploy (i.e. `https://octopus.example.app`). It is strongly recommended that this value be retrieved from a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions). | | `service_account_id` | The id of the OIDC service account you wish to login as. Service accounts can be viewed and created on the Octopus app under 'Users' on the configuration menu. | @@ -183,8 +187,8 @@ jobs: with: project: 'MyProject' release_number: '1.0.0' - git_ref: ${{ github.ref }} - git_commit: ${{ github.sha }} + git_ref: ${{ github.head_ref || github.ref }} + git_commit: ${{ github.event.pull_request.head.sha || github.sha }} packages: | HelloPackage:1.0.0 ``` @@ -267,8 +271,8 @@ jobs: with: project: 'MyProject' release_number: '1.0.0' - git_ref: ${{ github.ref }} - git_commit: ${{ github.sha }} + git_ref: ${{ github.head_ref || github.ref }} + git_commit: ${{ github.event.pull_request.head.sha || github.sha }} packages: | HelloPackage:1.0.0 ``` diff --git a/src/pages/docs/projects/version-control/creating-release-from-a-build-server-plug-in.mdx b/src/pages/docs/projects/version-control/creating-release-from-a-build-server-plug-in.mdx index a85a36bed5..79c9a2a103 100644 --- a/src/pages/docs/projects/version-control/creating-release-from-a-build-server-plug-in.mdx +++ b/src/pages/docs/projects/version-control/creating-release-from-a-build-server-plug-in.mdx @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2026-07-20 +modDate: 2026-09-15 title: Creating releases from a build server plugin on a version-controlled project description: Examples of how to ensure that the right branch is used to create the release when using a build server plugin. navOrder: 45 @@ -51,10 +51,10 @@ ${{ github.head_ref || github.ref }} For *Git Commit*, use ```text -${{ github.event.push.after || github.event.pull_request.head.sha }} +${{ github.event.pull_request.head.sha || github.sha }} ``` -**Note:** this approach doesn't populate the commit details for manually triggered runs. It is recommended that you provide the values for both branch and commit in this case. +On a pull request this resolves to the head of the source branch. On every other event, including manually triggered runs, it falls back to `github.sha`. ## TeamCity From c714a8c638acd265fccac0bdf3e75342f3fa231c Mon Sep 17 00:00:00 2001 From: robert Date: Wed, 16 Sep 2026 11:38:03 +1000 Subject: [PATCH 2/2] Keep the inputs table within its existing column width MD060 requires table pipes to align with the header. The longer git_ref and git_commit descriptions pushed those two rows past the width of the rest of the table. The hint above the table already explains the pull request behavior, so revert the two cells. --- .../packaging-applications/build-servers/github-actions.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/packaging-applications/build-servers/github-actions.mdx b/src/pages/docs/packaging-applications/build-servers/github-actions.mdx index dcec0f96b5..f476afebd6 100644 --- a/src/pages/docs/packaging-applications/build-servers/github-actions.mdx +++ b/src/pages/docs/packaging-applications/build-servers/github-actions.mdx @@ -116,8 +116,8 @@ On a pull request, `github.ref` is `refs/pull//merge` and `github.sha` i | `release_number` | The number for the new Release. If omitted, Octopus Deploy will generate a Release number. | | `environments` | A list of Environments in Octopus Deploy in which to run (i.e. Dev, Test, Prod). Add each environment on a new line. | | `variables` | A list of Variables to use in the Deployment in `key: value` format. Add each variable on a new line. | -| `git_ref` | The Git branch from which to source the project code. Required for Projects using version control in Octopus. The example above sources this value from the workflow's [contextual information](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context), using `github.head_ref` on pull requests so the release tracks the branch rather than the pull request merge ref. | -| `git_commit` | The Git commit from which to source the project code. Required for Projects using version control in Octopus. The example above sources this value from the workflow's [contextual information](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context), using `github.event.pull_request.head.sha` on pull requests so the release tracks the branch head rather than the merge commit. | +| `git_ref` | The Git branch from which to source the project code. Required for Projects using version control in Octopus. The example above sources this value from the workflow's [contextual information.](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context) | +| `git_commit` | The Git commit from which to source the project code. Required for Projects using version control in Octopus. The example above sources this value from the workflow's [contextual information.](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context) | | `server` | The base URL hosting Octopus Deploy (i.e. `https://octopus.example.app`). It is strongly recommended that this value be retrieved from a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions). | | `service_account_id` | The id of the OIDC service account you wish to login as. Service accounts can be viewed and created on the Octopus app under 'Users' on the configuration menu. |