How kiyoon/changelog-action works
Project type and purpose
• This is an open-source GitHub Action, written in TypeScript, whose sole purpose is to generate a Markdown CHANGELOG based on Conventional Commits between two Git tags (or commit refs).
• It is packaged for consumption on GitHub Marketplace and invoked inside GitHub workflows.
File structure
• Top-level files and folders:
• action.yml – metadata that defines inputs, outputs, and the entrypoint
• src/ – TypeScript source code:
– index.ts – main entrypoint
– index_testrun.ts – for local/testing scenarios
– utils/ – helper modules: github.ts, semver.ts(+spec), newFile.ts, set.ts
• dist/ – compiled JavaScript shipped to npm/GitHub Action runner
• .github/workflows/ – CI pipelines (auto-release, deploy)
• package.json, tsconfig.json, biome.jsonc, bun.lock – build/configuration
• That “action.yml” ties together the compiled dist/index.js, declares the inputs (token, version tags, exclude rules, etc.), and the one output (“changes”).
Key insights from README
• Describes how the Action is triggered (workflow_dispatch or on push), what inputs it accepts, and what outputs it emits.
• Explains two high-level use cases: generating a release PR changelog or generating a GitHub Release body.
• Outlines features such as PR linkification, breaking-change detection, file injection, and idempotence.
Main components
a. GitHub Runner (host environment)
b. Action Metadata & Entrypoint
– action.yml
– dist/index.js invoked by the runner
c. Core Modules
– CLI layer (index.ts) – read inputs, orchestrate flow
– GitHub API client (utils/github.ts) – fetch tags, commits, PRs
– SemVer logic (utils/semver.ts) – determine previous tag, sort commits
– File I/O (utils/newFile.ts) – read/write CHANGELOG.md
– Output setter (utils/set.ts) – set the “changes” output variable
d. External Systems
– GitHub REST API – to list tags, commits, PR details
– Git repository (local clone) – to run git commands if needed
e. Downstream steps (outside this Action)
– Pull-request creator or Release publisher consuming the output
Relationships and data flow
1. Runner reads action.yml → launches Node process (dist/index.js).
2. Entrypoint loads inputs (token, new-version-tag, previous-version-tag, etc.).
3. GitHub client module uses the token to call GitHub’s REST API → retrieves tags & commit history.
4. SemVer module computes the correct “previous” tag and filters commits by type/skip lists.
5. Markdown generator assembles commits into a versioned CHANGELOG snippet.
6. File I/O module optionally injects the snippet into CHANGELOG.md in the workspace.
7. Output setter publishes the generated snippet as the Action’s output (“changes”).
8. Subsequent workflow steps read this output to create PRs or Releases.
Architectural patterns and design principles
• Modular design: each util (GitHub API, semver, file I/O) is isolated for testability.
• Single Responsibility Principle: index.ts delegates work to specialized modules.
• Idempotence: File-inject logic checks and avoids duplicate entries.
• Configuration-driven behavior through action inputs (no hard-coded values).