With the GitHub CLI, what does `gh release create v1.4.1 --generate-notes ./dist/*.tar.gz` do when tag v1.4.1 is not yet on GitHub?
answer
- the tag has to come from somewhere
- default branch, not your checkout
- --target or --verify-tag
- draft first while assets upload
basics
~20 sgh asks GitHub to create tag v1.4.1 from the latest commit of the default branch, not your local checkout, unless --target names another branch or SHA; it generates the title and notes, and uploads the archives before publishing.
solid answer
~40 sWhen the tag is missing on GitHub, `gh release create` has GitHub create it from the **latest state of the default branch**. The commit you have checked out locally is not used, and `--target <branch|sha>` points the new tag elsewhere. `--verify-tag` aborts instead if the tag is not already in the remote repository. If the tag exists only locally, gh refuses and asks you to push it or pass `--target`. `--generate-notes` fills the notes from GitHub's release-notes API and generates a title unless `--title` is given. `--notes` text is prepended. Because assets are attached, gh creates the release as a draft, uploads the files, then publishes it, and it deletes the draft if an upload fails. Afterwards `git fetch --tags origin` brings the new tag down.
code
bash · 6 lines# Safe patch release: tag the fix on the release branch, push it, then verify
git switch release/1.4
git tag -a v1.4.1 -m "v1.4.1"
git push origin v1.4.1
gh release create v1.4.1 --verify-tag --generate-notes --latest=false \
'./dist/widgets-amd64.tar.gz#x86-64 build' ./dist/checksums.txtgo deeper
Recall that gh release create takes a tag, optional notes flags and asset files, and that --generate-notes writes the notes for you.
Explain where a missing tag is created, what --target and --verify-tag change, and why assets are uploaded to a draft before publishing.
Show the judgement for patch releases from maintenance branches: tag first with --verify-tag or target explicitly, keep Latest correct, and plan for immutable releases.
Weigh hand-run releases from a terminal against fully automated tag-driven releases, and what each means for provenance and for who may cut a release.
## Releases and tags A **GitHub release** is a page attached to a **Git tag**. It holds a title, release notes and downloadable **assets** such as archives and checksums. The tag is the anchor: it decides which commit the release describes. `gh release create` makes the release, and when the tag does not exist yet it decides where the tag goes. That decision is where on-call patch releases go wrong. ## Where the tag comes from | Situation | What `gh release create v1.4.1` does | |---|---| | Tag already on GitHub | uses it; no tag is created | | Tag missing everywhere, no `--target` | GitHub creates the tag from the **latest state of the default branch** | | Tag missing, `--target release/1.4` (or a full SHA) | GitHub creates the tag at that branch's tip or that commit | | Tag missing on GitHub, `--verify-tag` | aborts: the tag doesn't exist in the repository | | Tag exists only locally, no `--target` | refuses: the tag exists locally but has not been pushed | The second row is the trap. The engineer who fixed the bug on a `release/1.4` branch and runs `gh release create v1.4.1` from that checkout gets a tag on the default branch's tip. That is a different commit, possibly carrying unreleased features. The help says so directly: the tag is created from the latest state of the default branch, and `--target` points it at a different branch or commit. Two safe patterns: 1. **Tag first, then verify.** Create the tag with Git (annotated or signed if your process wants that), push it, and run `gh release create v1.4.1 --verify-tag`. The command aborts if the tag is not on GitHub, so it can never invent one. 2. **Target explicitly.** `gh release create v1.4.1 --target release/1.4` lets GitHub create the tag, at the commit you meant. The help also notes that a tag GitHub creates does not appear in your clone until you run `git fetch --tags origin`. ## Where the notes come from - `--generate-notes` asks GitHub's release-notes API to write the notes, usually a list of merged pull requests and contributors since the previous release. It also generates the release title unless you pass `--title`. Text given with `--notes` is put in front of the generated notes. - `--notes-start-tag <tag>` picks the tag the generated notes start from, instead of letting GitHub choose the previous release. - `--notes-from-tag` uses the annotation of a local annotated tag, or the commit message when the tag is not annotated. It cannot be combined with `--generate-notes` or `--notes-start-tag`. - `--notes` / `-n` and `--notes-file` / `-F` supply the text yourself. What the generated notes include and how they are grouped is set by GitHub's release-notes configuration in the repository, which is covered with releases themselves. ## How assets are attached Any file arguments after the tag are uploaded as assets. Appending `#text` to a path gives it a display label: `'./dist/widgets-amd64.tar.gz#x86-64 build'`. With assets present and no `--draft`, gh works in three API steps: 1. it creates the release as a **draft**; 2. it uploads every asset; 3. it **publishes** the release. If an upload fails, gh deletes the draft it created and reports the error, along with a note if that cleanup itself failed. Nobody downloads a half-populated release. This ordering also matters for **immutable releases**: when a repository enables them, the tag and assets of a published release can no longer be modified or deleted, and the help notes that the protection takes effect only once gh publishes the release. ## Other flags an on-call engineer reaches for - `--draft` / `-d` keeps the release as a draft for someone else to review and publish. - `--prerelease` / `-p` marks it as a prerelease. `--latest=false` stops it from becoming the repository's Latest release, which is useful when shipping v1.4.1 after v2.0 already exists. - `--fail-on-no-commits` fails if there are no commits since the last release. It has no effect on a repository's first release. - `--discussion-category` starts a discussion for the release, but not together with `--draft`. - Without a terminal, the tag argument is required. gh will not open an editor for notes, so a release created there with no notes flag simply has an empty body. The meaning of draft, prerelease and Latest on the release page, and whether to retag or ship a new patch after a broken release, are release-management questions. The CLI's part is creating the right tag and attaching the right files in one command.
- You ran `gh release create v1.4.1` from your `release/1.4` checkout and the release shows unreleased features. What happened, and how do you fix it?The tag did not exist on GitHub, so it was created from the default branch's tip, not your checkout. Remove the wrong release and its tag before anyone consumes them, then rerun with `--target release/1.4`, or push your own tag and use `--verify-tag`. Whether to reuse the version number at all is a release-policy decision.
- When would you use `--notes-from-tag` instead of `--generate-notes`?When the release notes are written by hand in an annotated tag's message, as part of a tagging process. `--notes-from-tag` copies that annotation, or the commit message when the tag is not annotated. It cannot be combined with `--generate-notes`, which lists merged pull requests through GitHub's API.
- gh release create tags the commit you currently have checked out
- --verify-tag creates the tag if it is missing and then verifies it
- If an asset upload fails, you are left with a half-published release
- --generate-notes needs a --title or the release ends up untitled
- --notes-from-tag and --generate-notes can be combined into one note