Package Changelog Action

• Inputs
  • Permissions
  • Changelog Options
  • Changelog Examples
• Outputs
• Examples
• Tags
• Features
  • Planned
• Support
• Contributing

Action to Generate Package Changelog. View some Changelog Examples.

On a release, this action will parse the differences in the provided package-lock.json file between the current and previous release and update the release notes with a table of changes.

On a prerelease it compares with the previous release, on a non-prerelease release, it compares with the previous non-prerelease.

Packages get sorted into the following categories and columns:

Name	❔	Operation	Before	After
@added	🆕	Added		current
@upgrade	✅	Upgraded	previous	current
@downgraded	⚠️	Downgraded	previous	current
@removed	⛔	Removed	previous
@unknown	❓	Unknown	previous	current
@unchanged	🔘	Unchanged	previous	current

Tip

Both Columns and Section Order and Visibility can be Customized!
See Changelog Options and Changelog Examples for more...

Inputs

Input	Req.	Default Value	Input Description
path	-	package-lock.json	Location of Lock File
update	-	true	Update Release Notes ⤵️
heading	-	### Package Changes	Release Notes Heading ⤵️
toggle	-	Click Here to View Changes	Toggle Text for Summary ⤵️
open	-	false	Summary Open by Default ⤵️
empty	-	false	Add Summary on No Changes ⤵️
columns	-	n,i,t,b,a	Customize Table Columns ⤵️
sections	-	a,u,d,r,k	Customize Package Sections ⤵️
max	-	30	Max Releases to Process
summary	-	true	Add Workflow Job Summary
token	-	github.token	For use with a PAT

You can add this to your release workflow with no inputs.

- name: 'Package Changelog Action'
  continue-on-error: true
  uses: cssnr/package-changelog-action@v1

Note: continue-on-error: true is set here so your release workflow won't fail if processing the changelog fails.

See the Changelog Options to customize the results.

Permissions

This action requires the following permissions to update release notes:

permissions:
  contents: write

Permissions documentation for Workflows and Actions.

Changelog Options

update: Set this to false if you only want to use the Outputs.

heading: You can customize the heading or set to an empty string to remove it.

toggle: The toggle must be set to a non-empty string if changing this input.

open: Set summary to be open by default (note the first example below is open).

empty: Set this to true to update release notes when no changes are detected.

columns: Customize column visibility and order. This must be a perfectly formatted CSV with any combination of these keys:

Default value: n,i,t,b,a

Key	Column	Column Description
n	Package Name	Name of the package
i	❔	Icon of the outcome
t	Outcome	Text of the outcome
b	Before	Version before change
a	After	Version after change

sections: Customize section visibility and order. This must be a perfectly formatted CSV with any combination of these keys:

Default value: a,u,d,r,k

Key	Section	Section Description
a	Added	Newly added package
u	Upgraded	Updated package version
d	Downgraded	Downgraded package version
r	Removed	Removed package
k	Unknown	Invalid semantic version
n	Unchanged	Package version not changed

Note: Enabling Unchanged n packages can produce a very long list.

View the Column and Section Maps

const maps = {
  col: {
    n: { align: 'l', col: 'Package Name' },
    i: { align: 'c', col: '❔' },
    t: { align: 'c', col: 'Operation' },
    b: { align: 'l', col: 'Before' },
    a: { align: 'l', col: 'After' },
  },
  sec: {
    a: { icon: '🆕', text: 'Added', key: 'added' },
    u: { icon: '✅', text: 'Upgraded', key: 'upgraded' },
    d: { icon: '⚠️', text: 'Downgraded', key: 'downgraded' },
    r: { icon: '⛔', text: 'Removed', key: 'removed' },
    k: { icon: '❓', text: 'Unknown', key: 'unknown' },
    n: { icon: '🔘', text: 'Unchanged', key: 'unchanged' },
  },
}

Changelog Examples

💡 Click on an example heading to expand or collapse the example.

Note: Examples are generated with an empty header and default values.

🔷 Default Example

---

Click Here to View Changes

Changes for: package-lock.json

Package Name	❔	Before	After
@eslint/config-helpers	🆕		0.1.0
@eslint-community/eslint-utils	✅	4.4.1	4.5.1
@eslint/core	✅	0.11.0	0.12.0
@eslint/eslintrc	✅	3.2.0	3.3.0
@eslint/js	✅	9.20.0	9.22.0
@eslint/plugin-kit	✅	0.2.5	0.2.7
@humanwhocodes/retry	✅	0.4.1	0.4.2
@octokit/endpoint	✅	9.0.5	9.0.6
@octokit/graphql	✅	7.1.0	7.1.1
@octokit/plugin-paginate-rest	✅	9.2.1	9.2.2
@octokit/request	✅	8.4.0	8.4.1
@octokit/request-error	✅	5.1.0	5.1.1
acorn	✅	8.14.0	8.14.1
eslint	✅	9.20.1	9.22.0
eslint-scope	✅	8.2.0	8.3.0
flatted	✅	3.3.2	3.3.3
prettier	✅	3.5.0	3.5.3
@eslint/plugin-kit/node_modules/@eslint/core	⛔	0.10.0

---

🔷 Example with No Changes

---

No changes detected in: package-lock.json

---

More Changelog Examples Coming Soon...

For more options, see the Changelog Options.

Outputs

Output	Output Description
json	Chnages JSON Object
markdown	Changes Markdown Table

This outputs the changes json object and the markdown table.

- name: 'Package Changelog Action'
  id: changelog
  uses: cssnr/package-changelog-action@v1

- name: 'Echo Output'
  env:
    JSON: ${{ steps.changelog.outputs.json }}
    MARKDOWN: ${{ steps.changelog.outputs.markdown }}
  run: |
    echo "json: '${{ env.JSON }}'"
    echo "markdown: '${{ env.MARKDOWN }}'"

Note: due to the way ${{}} expressions are evaluated, multi-line output gets executed in a run block.

JSON Schema

{
  "added": [{ "name": "", "after": "" }],
  "downgraded": [{ "name": "", "before": "", "after": "" }],
  "removed": [{ "name": "", "before": "" }],
  "unchanged": [{ "name": "", "before": "", "after": "" }],
  "unknown": [{ "name": "", "before": "", "after": "" }],
  "upgraded": [{ "name": "", "before": "", "after": "" }]
}

More Output Examples Coming Soon...

Examples

💡 Click on an example heading to expand or collapse the example.

Custom Heading

- name: 'Package Changelog Action'
  uses: cssnr/package-changelog-action@v1
  with:
    heading: '**NPM Changelog**'

Custom Column Order

- name: 'Package Changelog Action'
  uses: cssnr/package-changelog-action@v1
  with:
    columns: 'n,t,b,a'

This removes the icon column.

Custom Section Order

- name: 'Package Changelog Action'
  uses: cssnr/package-changelog-action@v1
  with:
    sections: 'u,a,d,r,k'

This changes the section order to put Updated before Added.

Use Outputs Only

- name: 'Package Changelog Action'
  id: changelog
  uses: cssnr/package-changelog-action@v1
  with:
    update: false

- name: 'Echo Output'
  env:
    JSON: ${{ steps.changelog.outputs.json }}
    MARKDOWN: ${{ steps.changelog.outputs.markdown }}
  run: |
    echo "json: '${{ env.JSON }}'"
    echo "markdown: '${{ env.MARKDOWN }}'"

Full Workflow Example

name: 'Release'

on:
  release:
    types: [published]

jobs:
  release:
    name: 'Release'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      contents: write

    steps:
      - name: 'Package Changelog Action'
        uses: cssnr/package-changelog-action@v1
        continue-on-error: true

More Examples Coming Soon...

Tags

The following rolling tags are maintained.

Version Tag	Rolling	Bugs	Feat.	Name	Target	Example
	✅	✅	✅	Major	vN.x.x	vN
	✅	✅	❌	Minor	vN.N.x	vN.N
	❌	❌	❌	Micro	vN.N.N	vN.N.N

You can view the release notes for each version on the releases page.

The Major tag is recommended. It is the most up-to-date and always backwards compatible. Breaking changes would result in a Major version bump. At a minimum you should use a Minor tag.

Features

• Automatically parse differences between package-lock.json changes between releases.
• Sorts into sections: Added, Upgraded, Downgraded, Removed, Unknown, Unchanged.
• Option to customize sections visibility and sections order.
• Option to customize columns visibility and columns order.
• Option to display results expanded or collapsed.
• Outputs changes in JSON and markdown.

Planned

• Work on Pull Requests
• Work on Workflow Dispatch
• Custom Column Alignment
• Custom Column Titles
• Custom Section Icons
• Custom Section Text

Want to show outdated packages on a pull request? Check out: cssnr/npm-outdated-action
Want to automatically updated tags on release? Check out: cssnr/update-version-tags-action

If you would like to see a new feature, please submit a feature request.

Support

For general help or to request a feature, see:

• Q&A Discussion: https://github.com/cssnr/package-changelog-action/discussions/categories/q-a
• Request a Feature: https://github.com/cssnr/package-changelog-action/discussions/categories/feature-requests

If you are experiencing an issue/bug or getting unexpected results, you can:

• Report an Issue: https://github.com/cssnr/package-changelog-action/issues
• Chat with us on Discord: https://discord.gg/wXy6m2X8wY
• Provide General Feedback: https://cssnr.github.io/feedback/

For more information, see the CSSNR SUPPORT.md.

Contributing

Currently, the best way to contribute to this project is to star this project on GitHub.

For more information, see the CSSNR CONTRIBUTING.md.

Additionally, you can support other GitHub Actions I have published:

• Stack Deploy Action
• Portainer Stack Deploy
• VirusTotal Action
• Mirror Repository Action
• Update Version Tags Action
• Update JSON Value Action
• Parse Issue Form Action
• Cloudflare Purge Cache Action
• Mozilla Addon Update Action
• Docker Tags Action
• Package Changelog Action
• NPM Outdated Check Action

For a full list of current projects to support visit: https://cssnr.github.io/