ncipollo/release-action: GitHub release creation from workflows

Release-action targets GitHub Actions release steps

ncipollo/release-action addresses a specific automation problem: creating a GitHub release from a CI workflow and attaching one or more artifacts. It is intended for repository maintainers who publish tagged software from GitHub Actions rather than engineers seeking a general command-line release tool. The README describes both release creation and optional artifact upload as the action's central responsibilities.

The action also handles cases that commonly appear after a release workflow has been configured. It can update an existing release when `allowUpdates` is enabled, preserve selected fields during an update, automatically generate release notes, mark a release as a draft, and create a discussion in an existing category. This gives workflow authors one place to configure several GitHub release policies, although it remains tied to GitHub's release and discussions features.

The README excerpt does not show marketplace installation syntax or a complete workflow example. It also does not document how the caller should supply the GitHub token. Those details should be confirmed in `action.yml` and the full README before this action is added to a production workflow. The repository's default branch is `main`, so workflow references need to match the documented action reference rather than an assumed branch name.

Inputs separate release metadata from artifact behavior

The action exposes release metadata and upload policy as separate inputs. `name` sets the release title, while an omitted title falls back to the tag. `body` supplies an inline description, although the README warns that leading and trailing whitespace is trimmed and recommends `bodyFile` for non-trivial Markdown. `commit` selects the commit reference used when the tag has to be created.

Artifact handling has its own controls. `artifacts` accepts a single path, comma-delimited paths, or globs. `artifactContentType` defaults to `raw`, and `artifactErrorsFailBuild` determines whether artifact reading or upload errors fail the build. The separation is useful because release metadata may still need to be published when an artifact is absent or an upload has an error. It also means that missing or unreadable artifacts can be an intentional choice, depending on that flag.

Release state is controlled by `draft`, `makeLatest`, `generateReleaseNotes`, and `discussionCategory`. `generateReleaseNotesPreviousTag` can limit generated notes to changes between two tags. `discussionCategory` requires an existing category and the `discussions: write` permission, and it is ignored for draft releases according to the README. These inputs expose several GitHub release policies without changing action source code.

Existing-release updates are opt-in and field-sensitive

By default, the action does not update a release that already exists because `allowUpdates` defaults to `false`. This default favors preventing accidental mutation of published release records. A workflow that needs replacement or repair behavior must explicitly enable updates and decide which fields it is willing to send.

That second decision matters because the action provides preservation-oriented options. `omitBodyDuringUpdate` leaves an existing body unchanged while still allowing the body to be applied when a release is first created. `omitDraftDuringUpdate` preserves the existing draft state under the same create-versus-update distinction. These controls are narrower than a blanket update mode and reduce the need to reconstruct fields that the workflow did not originally manage.

The feature set still has a clear operational boundary. Updates are performed against a GitHub release identified through GitHub's API and the configured tag context. The README does not document conflict handling for concurrent workflows, rollback behavior, or recovery after a partially completed update. A workflow that can publish the same tag from multiple jobs should treat concurrency as an unresolved design issue rather than assume that `allowUpdates` provides serialization.

Immutable creation changes the publish order

The `immutableCreate` option changes how the action approaches publication. According to the README, it first creates a draft release, uploads the artifacts, and then publishes the release. This ordering prevents the public release from existing before its attached files have completed uploading.

That sequence is meaningful for packages whose users may begin downloading files as soon as a release becomes visible. It also changes failure behavior. If artifact upload fails after the draft is created but before publication, the repository may contain an unpublished draft rather than a completed public release. The README says artifact errors can be allowed not to fail the build through `artifactErrorsFailBuild`, but it does not explain automatic cleanup of that draft.

`immutableCreate` should therefore be understood as a publication workflow, not just a boolean convenience. Teams using it need to decide what should happen when an artifact is missing, especially if the failure is not intended to stop the build. The action exposes the relevant controls, but the README does not promise rollback or automatic deletion.

TypeScript sources produce a distributable GitHub Action

The repository layout shows a conventional TypeScript action project. Source code is under `src/`, tests are under `__tests__/`, and mocks are under `__mocks__/`. The root contains `action.yml`, while `dist/` is present for the packaged action artifact. The package configuration sets the project to ES modules and declares Node.js `>=20` as its engine requirement.

The implementation uses `@actions/core` for action inputs and outputs, `@actions/github` for GitHub integration, and `glob` for resolving artifact paths. The test and packaging toolchain includes TypeScript, Vitest, Biome, and `@vercel/ncc`. `package.json` provides separate scripts for compilation, testing, formatting, cleanup, packaging, and a combined release build.

The relevant package commands are available in the repository configuration. Contributors can run the test suite, produce TypeScript output, or package the action with the commands below. The repository does not show the contents of `action.yml` here, so the exact action entry point and runtime configuration cannot be confirmed.

pnpm test

This invokes Vitest once, as defined by the `test` script. A contributor would expect this command to exercise the checked-in test suite.

pnpm build
pnpm package

The first command invokes `tsc`. The second invokes `ncc` with source maps and license generation. Contributors changing the source should consult `action.yml` and the project's release instructions before treating either output as ready for workflow use.

Release creation is not a full release-management suite

The strongest alternative for some workflows is a direct sequence of GitHub CLI commands in the job itself. That approach avoids adding this action when the only requirements are creating a release and uploading a small set of files. Its tradeoff is that artifact matching, update preservation, generated notes, and discussion handling are not represented by a single reusable action configuration.

Another alternative is GitHub's built-in release support when the workflow only needs the repository's standard release behavior and does not require this action's optional update controls. The README does not claim that `ncipollo/release-action` replaces deployment, changelog authorship, signing, or release approval policy. Those concerns remain outside the documented scope.

The action is consequently best suited to workflows that value configurable GitHub release mechanics over a minimal pipeline. It is less suitable when a team needs documented local installation, a general-purpose release CLI, or explicit rollback and concurrency guarantees. Those missing guarantees should not be inferred from the presence of `allowUpdates` or `immutableCreate`.

Recent maintenance carries a TypeScript upgrade burden

The repository is not archived, and its last push was on 2026-10-16. Recent release history includes `v1.21.0` on 2026-03-14 and `v1.20.0` on 2025-09-02. This shows recent repository activity, but the repository files do not establish a long-term compatibility policy or release schedule.

Consumers still inherit the maintenance cost of a Node-based GitHub Action. The current `package.json` requires Node.js `>=20` and lists current major-version dependencies, including `@actions/core` `^3.0.0` and `@actions/github` `^9.0.0`. A workflow that pins an old action reference may retain older behavior until its maintainers update that reference. The repository's package version is `1.1.0`, while GitHub release tags are separately named, so the package version should not be used as the workflow version.

The project uses the MIT license. Workflow owners remain responsible for reviewing the license text and dependencies relevant to their distribution and compliance requirements. No separate hosted service, usage fee, or support contract is documented.

Workflow adoption needs an input and permission checklist

There is no complete install tutorial in the README excerpt, so a new user should not copy an invented marketplace reference or token setting. Start with `action.yml` to confirm the action name, entry point, inputs, outputs, and required runtime. Then confirm the full README for the current invocation syntax and token permissions.

For a first real use, keep the configuration narrow: create a release from an existing tag, provide a concise body, and optionally attach one explicitly named artifact. Decide separately whether artifact errors should fail the build. Avoid enabling updates, immutable creation, generated notes, and discussions at the same time, because each option changes failure handling or publication order.

Before adopting it in an existing release pipeline, check five concrete details. First, confirm how the workflow token is passed. Second, verify that every `artifacts` path resolves to the files intended for publication. Third, inspect the permissions required for release operations and, if applicable, `discussions: write`. Fourth, test the exact update fields and preservation flags against a non-production tag. Fifth, confirm the expected behavior when an artifact upload fails, especially with `immutableCreate`.

Editorial conclusion

Engineers with GitHub Actions release workflows should consider this action when they need direct control over release creation, artifact upload, updates, and discussion creation. It is a poor fit for teams that require fully documented setup or simple local release management outside GitHub Actions. Check `action.yml`, the complete input reference, token permissions, artifact paths, and update behavior before adopting it.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. ncipollo/release-action on GitHub
4. README
5. Releases