From 235b8fd65e7fe4fd262f30661a80d2e83c51b446 Mon Sep 17 00:00:00 2001 From: robert Date: Wed, 16 Sep 2026 11:56:09 +1000 Subject: [PATCH] docs: use pull request safe git_ref and git_commit 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. It also disagrees with what the workflow built, since builds normally check out the branch head. Update the version controlled example and the git_ref and git_commit input descriptions to use github.head_ref and github.event.pull_request.head.sha, both of which fall back to the push values on every other event. This matches the advice already given for git_resources further down the README. --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1b9bca7a..51a0dde9 100644 --- a/README.md +++ b/README.md @@ -56,10 +56,12 @@ steps: uses: OctopusDeploy/create-release-action@v4 with: project: 'MyProject' - 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 }} ``` +Resolve both values per event so the release tracks the branch you built. 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 is not reachable from any branch or tag, so a release pinned to it can fail to deploy later. `github.head_ref` and `github.event.pull_request.head.sha` give you the source branch and its head commit, and both fall back to the push values on every other event. + To specify the version of a package referenced in a step to use in the release, add the `packages` field: ```yml @@ -115,8 +117,8 @@ steps: | `package_version` | The version number of all packages to use for this release. | | `packages` | A multi-line list of version numbers to use for a package in the release. Format: StepName:Version or PackageID:Version or StepName:PackageName:Version. StepName, PackageID, and PackageName can be replaced with an asterisk ("\*"). An asterisk will be assumed for StepName, PackageID, or PackageName if they are omitted. **NOTE** these values should not be enclosed in single-quotes (`'`) | | `git_resources` | A multi-line list of Git references to use for a step's Git resource, resolved at release-creation time. Useful for steps that read from a Git repository — such as **Update Argo CD Application Manifests** — so a release can target a specific branch/tag (e.g. a feature branch). Format: StepName:GitRef or StepName:GitResourceName:GitRef (e.g. `Update Argo CD Application Manifests:refs/heads/my-feature`). Note: `git_ref`/`git_commit` select the version-controlled project's own OCL branch; `git_resources` selects the branch/tag of a Git resource used by a step. | -| `git_ref` | Git reference, _branch name or tag_, to the specific resources of a version controlled Octopus Project. This should be used for version controlled projects when OCL files are stored in a different repository or branch as the application being built. E.g. Use the `main` branch, regardless of the location of the repository where the application(s) are being built as they are different **or** `${{ github.ref }}` to use the branch or tag ref that triggered the workflow. | -| `git_commit` | Git commit, _commit SHA-1 hash_, pointing to the specific resources of a version controlled Octopus Project. This should be used for version controlled projects when OCL files are stored in the same repository or branch as the application being built. E.g. `${{ github.sha }}` to use the commit that triggered the workflow. | +| `git_ref` | Git reference, _branch name or tag_, to the specific resources of a version controlled Octopus Project. This should be used for version controlled projects when OCL files are stored in a different repository or branch as the application being built. E.g. Use the `main` branch, regardless of the location of the repository where the application(s) are being built as they are different **or** `${{ github.head_ref \|\| github.ref }}` to use the branch or tag that triggered the workflow. Avoid `${{ github.ref }}` on its own, because on a pull request it is `refs/pull//merge` and pins the release to a merge commit that no branch reaches. | +| `git_commit` | Git commit, _commit SHA-1 hash_, pointing to the specific resources of a version controlled Octopus Project. This should be used for version controlled projects when OCL files are stored in the same repository or branch as the application being built. E.g. `${{ github.event.pull_request.head.sha \|\| github.sha }}` to use the commit that triggered the workflow. Avoid `${{ github.sha }}` on its own, because on a pull request it is the merge commit GitHub creates for the pull request rather than the head of the branch that was built. | | `ignore_existing` | Ignore existing releases if present in Octopus Deploy with the matching version number. Defaults to **false** | | `release_notes` | The release notes text associated with the new release (Markdown is supported). | | `release_notes_file` | A file containing the release notes associated with the new release (Markdown is supported). Use either `release_notes` or this input, supplying both is not supported. |