release-flow.md

release-flow.md

is it possible to interact with GitHub release via cli. like GitHub CLI api library? or smth like that?

Yes—GitHub releases can be fully managed from the command line using GitHub CLI (gh), and for anything not covered by built-in commands you can call the GitHub REST API from the CLI as well.¹²

Using GitHub CLI for releases

GitHub CLI has a dedicated gh release command group for managing releases.² Common operations include creating, listing, viewing, and deleting releases, plus uploading/deleting assets.³²

Examples:²³

• List releases: gh release list²
• View latest release: gh release view (without a tag, it shows the latest)⁴
• Create a release: gh release create v1.0.0⁵³
• Upload assets during create (supported by gh release create, which uploads assets and then publishes): gh release create v1.0.0 ./dist/*³

Calling the GitHub API from CLI

If you need “API-like” flexibility, gh api lets you make authenticated requests to GitHub’s REST API endpoints directly from the terminal.¹ Releases are covered by GitHub’s REST API “releases” endpoints (create, edit, delete, list, etc.).⁶ Release assets (including downloading asset binaries) are covered by the REST API “release assets” endpoints.⁷

“CLI API library” option

If the goal is programmatic interaction (e.g., building a GitHub CLI extension), GitHub provides go-gh, a Go library designed to follow GitHub CLI conventions and includes an API client module.⁸

What language are you scripting in (bash, Python, Go, etc.), and do you mainly need to create releases, upload assets, or download assets? ^{9101112131415161718}

⁂

---

what would be the flow if I want to make a release from files to include, change log to include, title, tag etc. what would be the potential steps etc?

A typical flow is: decide (or create) the git tag you want to release, prepare your release notes (changelog) and asset files, then run gh release create with --title, --notes/--notes-file (or note-generation flags), and the file paths/patterns for assets.¹⁹

Decide tag and target

Pick the release tag (for example v1.4.0) and whether it should point at the default branch tip or a specific branch/commit SHA.¹⁹ If the tag doesn’t exist yet, gh release create <tag> will create it automatically from the latest state of the default branch, unless --target is used to point at a different branch or commit.¹⁹ If a tag must already exist (for stricter automation), use --verify-tag to abort when the remote tag is missing.¹⁹

Prepare release notes (changelog)

Write the changelog content ahead of time and pass it as inline text with --notes, or from a file with --notes-file (using - to read from stdin).¹⁹ If you maintain annotated tags, you can generate the release notes from the tag annotation using --notes-from-tag (and if the tag is not annotated, the commit message is used).¹⁹ If you want GitHub to generate notes (and usually a title), use --generate-notes, and optionally prepend extra text by also providing --notes.¹⁹

Collect files (assets) to include

Gather the build artifacts you want attached to the release and pass them as filenames or glob patterns after the tag in the gh release create command.¹⁹ If you want a custom display label for a given asset, append # and the label text to the filename argument.¹⁹ If you expect “empty” releases to be an error in CI, use --fail-on-no-commits to fail when there are no new commits since the last release.¹⁹

Create as draft, then publish (common safe flow)

Create a draft first (so you can double-check title/notes/assets) by using --draft, then edit/upload as needed, and finally publish (for example by running gh release edit to toggle draft state).¹⁹ This draft-first approach aligns with how gh release create attaches assets: it creates the release as a draft, uploads assets, and then publishes it (unless you keep it draft).¹⁹ If your repo has release immutability enabled, note that protections (no modifying/deleting tags/assets) apply after a release is published, while drafts can still be modified or deleted.¹⁹

Example command (putting it together)

• gh release create v1.4.0 dist/* --title "v1.4.0" --notes-file CHANGELOG.md --target main¹⁹

Do you want the changelog to be auto-generated from GitHub PRs/issues (--generate-notes), or do you maintain a curated CHANGELOG.md that should be used verbatim?

⁂

Footnotes

1. https://cli.github.com/manual/gh_api ↩ ↩²

2. https://cli.github.com/manual/gh_release ↩ ↩² ↩³ ↩⁴ ↩⁵

3. https://cli.github.com/manual/gh_release_create ↩ ↩² ↩³ ↩⁴

4. https://stackoverflow.com/questions/34899736/how-can-i-use-git-cli-to-get-the-latest-release ↩

5. https://www.freecodecamp.org/news/how-to-use-github-from-the-command-line/ ↩

6. https://docs.github.com/en/rest/releases/releases ↩

7. https://docs.github.com/rest/releases/assets ↩

8. https://github.com/cli/go-gh ↩

9. https://stackoverflow.com/questions/21214562/how-to-release-versions-on-github-through-the-command-line ↩

10. https://www.npmjs.com/package/github-release-cli ↩

11. https://docs.github.com/en/github-cli/github-cli/about-github-cli ↩

12. https://cli.github.com ↩

13. https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository ↩

14. https://www.youtube.com/watch?v=Somvl-qh2dk ↩

15. https://github.blog/engineering/engineering-principles/scripting-with-github-cli/ ↩

16. https://docs.github.com/en/rest/quickstart ↩

17. https://github.com/cli/cli/discussions/3820 ↩

18. http://mh-cbon.github.io/gh-api-cli/ ↩

19. https://cli.github.com/manual/gh_api ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³ ↩¹⁴