`release not found` by GitHub CLI when attempting to download a named release by its release name

Question

A release not found error is being thrown with exit code 1 even when we cut and paste the precise name of a release that is returned by the gh release list --repo $repoWithToken command that runs immediately before.

The relevant portions of the GitHub error log are:

About list releases
exact_name_of_release_linux_n.1.2       _linux_n.1.2    2022-09-19T23:28:08Z
About to download release
release not found
Error: Process completed with exit code 1.

The complete code of the workflow is as follows:

download-a-release-linux:
  runs-on: ubuntu-latest
  steps:
    - shell: bash
      name: Download a Release
      env:
        VERSION: ${{ inputs.version }}
        GH_TOKEN: ${{ secrets.GITPAT }}
      run: |
        echo "About list releases"
        repoWithToken="https://"$GH_TOKEN"@github.com/accountName/repoName"
        gh release list --repo $repoWithToken
        echo "About to download release"
        gh release download exact_name_of_release_linux_n.1.2 --repo $repoWithToken
        echo "About to list contents of directory after download"
        ls -al

The $repoWithToken variable is being populated correctly because the gh release list --repo $repoWithToken command runs without error as shown in the logs above.

The above uses docs from this link.

The same error is thrown when we change the command to use the tag name as gh release download _linux_n.1.2 --repo $repoWithToken to more closely resemble the example given in the docs in the link.

Question

What specifically needs to be changed in the gh release download CLI command in the GitHub workflow code below in order for the exact_name_of_release_linux_n.1.2 release to be successfully downloaded?

Steps to Reproduce

1. Create an empty repo with nothing other than:

   • a workflow file that includes the download-a-release-linux job shown above, and
   • a main.py file with a simple print("Hello World") command to represent an app.

2. Create a release using the API as follows, which can be done in a preceding job in the same workflow above:

   gh api \
     --method POST \
     -H "Accept: application/vnd.github+json" \
     /repos/AccountName/RepoName/releases \
     -f tag_name=$vers \
     -f target_commitish='source-branch-name' \
     -f name=$nameOfRelease \
     -f body="$DESCRIPTION" \
     -F draft=false \
     -F prerelease=false \
     -F generate_release_notes=false 
   

3. Get the name of the release, which above we are calling exact_name_of_release_linux_n.1.2

4. Run the workflow that contains the download-a-release-linux job using the code above with whatever modifications are required to get it to successfully download the release and list the valid contents of the app that are included in the release.

Answer 1

Read the docs that you linked carefully. According to the docs for gh release download, the command takes a git tag name- not a GitHub release name.

gh release download [<tag>] [flags]

"exact_name_of_release_linux_n.1.2" is a GitHub release name- not a release git tag name. _linux_n.1.2 is the git tag name for that release. At the time of this writing, the docs for gh release list don't actually explain what each column of the output table mean. I only knew by reading the source code of the GitHub cli tool. I'll explain later.

Answer

What specifically needs to be changed in the gh release download cli command in the GitHub workflow code below in order for the exact_name_of_release_linux_n.1.2 release to be successfully downloaded?

You need to change your call to gh release download to use the git tag name of the release instead of the name of the GitHub release.

# ...
jobs:
  download-a-release-linux:
    runs-on: ubuntu-latest
    steps:
      - shell: bash
        name: Download a Release
        env:
          VERSION: ${{ inputs.version }}
          GH_TOKEN: ${{ secrets.GITPAT }}
        run: |
          echo "About to list releases"
          repoWithToken="https://"$GH_TOKEN"@github.com/accountName/repoName"
          gh release list --repo $repoWithToken
          echo "About to download release"
          gh release download _linux_n.1.2 --repo $repoWithToken
          echo "About to list contents of directory after download"
          ls -al
# ...

Note (since you commented about this in confusion): the tarball and zipball are not part of the assets list of the release even though they are displayed in the same list as the other actual assets of the release in the GitHub releases UI. If you want to download those, use the --archive argument of the gh release download command.

Also, I don't think you need to use repoWithToken if you are already setting the GH_TOKEN environment variable. You should just be able to use accountName/repoName.

An Exercise in Reading Source Code

Note: This is applicable to the source code of the v2.16.1 release, but future behaviour may change.

If you look at the source code implementing the gh release list command, you'll see that it prints a table where the columns are:

1. The release name (which defaults to the git tag if no release name was set for the release)
2. A "badge" indicating if the release is the latest release, a draft release, or a pre-release
3. The git tag of the release (which is what gh release download expects to receive)
4. The publish date of the release

If you look at the source code implementing the gh release download command, you'll see that the "release not found" error is returned when FindDraftRelease doesn't find any releases, and tracing calls to FindDraftRelease, that it is called when FetchRelease's attempt to find a release with the given git tag doesn't find any non-draft releases when it makes a GitHub rest api call to get a release by a git tag.

I have opened an issue for discussion with the maintainers of the GitHub cli tool on the topic of the gh release list command's table columns' meanings not being explicitly documented. The issue has been resolved with an update which adds a header row labeling what each column of the output means.