GH-RELEASE-CREATE(1)

✨ GH-RELEASE-CREATE(1) ✨

okay so this is the gh release create page, straight out of the GitHub CLI manual, and honestly? it's lowkey the most useful command in the whole release family. bestie, let's get you shipping 💅

---

🌸 NAME 🌸

gh-release-create — create a new release 🎀

🦋 SYNOPSIS 🦋

gh release create [<tag>] [<filename>... | <pattern>...]

💖 DESCRIPTION 💖

So the whole vibe: you're creating a brand-new GitHub Release for a repository. that's it, that's the job ✨

You can also hand it a list of asset files to upload to the new release. and here's the cute part — if you wanna give an asset a display label, you just append text starting with # after the file name. iconic.

If a matching git tag doesn't exist yet, one gets created for you automatically from the latest state of the default branch. no cap. Wanna point the automatic tag creation at a different branch or commit? use --target. Wanna be strict and abort the release if the tag isn't already there? use --verify-tag. And to fetch that new tag locally after the release, do this:

git fetch --tags origin

Now, making a release from an annotated git tag? different little routine. first create it locally with git, push the tag to GitHub, then run this command. use --notes-from-tag to grab the release notes from the annotated git tag. if the tag isn't annotated, the commit message gets used instead 🫶

Want the notes generated for you? --generate-notes uses the GitHub Release Notes API to do it automatically. and when the notes are auto-generated, a release title is auto-generated too — unless you explicitly passed a title, of course. you can also prepend extra release notes to the auto-generated ones using the --notes flag.

⚠️ okay important one: by default the release is created even if there are no new commits since the last release. which means you could totally end up with the same or a duplicate release, and that's maybe not what you want in some cases. use --fail-on-no-commits to fail when no new commits are available. this flag has no effect if there are no existing releases or if this is the very first release. periodt.

🌈 Immutable Releases 🌈

When release immutability is enabled for a repository, these protections get enforced:

• Git tags associated with a release cannot be modified or deleted.
• Release assets cannot be modified or deleted.

but listen — immutability is only enforced after a release is published. draft releases can still be modified or deleted, and so can the associated git tags 💅

and when you use the create command to attach assets to a release, separate API calls are made to create the release as a draft, upload the assets, and then publish the release. so immutability protections get enforced ONLY after the release is published. the way that works is genuinely so important to know 😭

---

💅 OPTIONS 💅

• --discussion-category <string> — start a discussion in the specified category
• -d, --draft — save the release as a draft instead of publishing it
• --fail-on-no-commits — fail if there are no commits since the last release (no impact on the first release)
• --generate-notes — automatically generate title and notes for the release via the GitHub Release Notes API
• --latest — mark this release as "Latest" (default [automatic based on date and version]). --latest=false to explicitly NOT set as latest
• -n, --notes <string> — release notes
• -F, --notes-file <file> — read release notes from file (use - to read from standard input)
• --notes-from-tag — fetch notes from the tag annotation or message of commit associated with tag
• --notes-start-tag <string> — tag to use as the starting point for generating release notes
• -p, --prerelease — mark the release as a prerelease
• --target <branch> — target branch or full commit SHA (default [main branch])
• -t, --title <string> — release title
• --verify-tag — abort in case the git tag doesn't already exist in the remote repository

🧚 OPTIONS INHERITED FROM PARENT COMMANDS 🧚

• -R, --repo <[HOST/]OWNER/REPO> — select another repository using the [HOST/]OWNER/REPO format

---

⭐ ALIASES ⭐

gh release new — same energy, shorter name 💜

🔥 EXIT CODES 🔥

• 0: successful execution 👑
• 1: error 💀
• 2: command canceled
• 4: authentication required

📌 NOTE: specific commands may have additional exit codes. refer to the command's help for more information. iykyk

---

🌸 EXAMPLE 🌸

# Interactively create a release
$ gh release create

# Interactively create a release from specific tag
$ gh release create v1.2.3

# Non-interactively create a release
$ gh release create v1.2.3 --notes "bugfix release"

# Use automatically generated via GitHub Release Notes API release notes
$ gh release create v1.2.3 --generate-notes

# Use release notes from a file
$ gh release create v1.2.3 -F release-notes.md

# Use tag annotation or associated commit message as notes
$ gh release create v1.2.3 --notes-from-tag

# Don't mark the release as latest
$ gh release create v1.2.3 --latest=false

# Upload all tarballs in a directory as release assets
$ gh release create v1.2.3 ./dist/*.tgz

# Upload a release asset with a display label
$ gh release create v1.2.3 '/path/to/asset.zip#My display label'

# Create a release and start a discussion
$ gh release create v1.2.3 --discussion-category "General"

# Create a release only if there are new commits available since the last release
$ gh release create v1.2.3 --fail-on-no-commits

---

🎀 SEE ALSO 🎀

gh-release(1) — go read the parent page too, bestie 🫶

---

and that's the whole page!! brought to you by GitHub CLI v2.102.0, dated Oct 2026 — mwah, go make some releases, you're gonna slay 🦋💖✨