### File Configuration Example (configuration.json)

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/configuration.md

An example of a configuration file (e.g., configuration.json) that can be used to override default settings. This example shows how to modify pull request limits and define custom categories.

```json
{
  "max_pull_requests": 500,
  "sort": {
    "order": "DESC",
    "on_property": "mergedAt"
  },
  "categories": [
    {
      "key": "breaking",
      "title": "## ⚠️ Breaking Changes",
      "labels": ["breaking"]
    }
  ]
}
```

--------------------------------

### Full Changelog Builder Configuration Example

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/README.md

An extensive example showcasing all possible configuration options for the release-changelog-builder-action. Defaults apply for any omitted settings.

```json
{
    "categories": [
      {
        "title": "## 🚀 Features",
        "labels": ["feature"]
      },
      {
        "title": "## 🐛 Fixes",
        "labels": ["fix"]
      },
      {
        "key": "tests",
        "title": "## 🧪 Tests",
        "labels": ["test"]
      },
      {
        "title": "## 🧪 Tests and some 🪄 Magic",
        "labels": ["test", "magic"],
        "exclude_labels": ["no-magic"],
        "exhaustive": true,
        "exhaustive_rules": "false",
        "empty_content": "- no matching PRs",
        "rules": [
          {
            "pattern": "open",
            "on_property": "status",
            "flags": "gu"
          }
        ]
      }
    ],
    "ignore_labels": [
      "ignore"
    ],
    "sort": {
      "order": "ASC",
      "on_property": "mergedAt"
    },
    "template": "#{{CHANGELOG}}\n\n<details>\n<summary>Uncategorized</summary>\n\n#{{UNCATEGORIZED}}\n</details>",
    "pr_template": "- #{{TITLE}}\n   - PR: ##{{NUMBER}}",
    "empty_template": "- no changes",
    "label_extractor": [
      {
        "pattern": "(.) (.+)",
        "target": "$1",
        "flags": "gu"
      },
      {
        "pattern": "\[Issue\]",
        "on_property": "title",
        "method": "match"
      }
    ],
    "duplicate_filter": {
      "pattern": "\[ABC-....\]",
      "on_property": "title",
      "method": "match"
    },
    "reference": {
      "pattern": ".*\\ \#(.).*",
      "on_property": "body",
      "method": "replace",
      "target": "$1"
    },
    "transformers": [
      {
        "pattern": "[\\-\\*] ([\[(...|TEST|CI|SKIP)\]])( )?(.+?[\\-\\*] )(.+?[\\-\\*] )(.+)",
        "target": "- $4\n  - $6"
      }
    ],
    "trim_values": false,
    "max_tags_to_fetch": 200,
    "max_pull_requests": 200,
    "max_back_track_time_days": 365,
    "exclude_merge_branches": [
      "Owner/qa"
    ],
    "tag_resolver": {
      "method": "semver",
      "filter": {
        "pattern": "api-(.+)",
        "flags": "gu"
      }
    },
    "base_branches": [
      "dev"
    ]
}
```

--------------------------------

### Starting Tag Input

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/github-actions-io.md

Specify the starting tag or ref for changelog generation. If omitted, it's auto-resolved.

```yaml
with:
  fromTag: 'v1.0.0'
```

--------------------------------

### Example Workflow: Fetch Merged Pull Requests

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-pull-requests.md

Demonstrates fetching merged pull requests between two version tags. This snippet requires setup with repository, commits, and pull request services. It highlights various configuration options for fetching PR data.

```typescript
import {PullRequests} from './pullRequests.js'
import {Commits} from './commits.js'
import {GithubRepository} from '../repositories/GithubRepository.js'

const repository = new GithubRepository(token, undefined, '/repo')
const commits = new Commits(repository)
const pulls = new PullRequests(repository, commits)

// Fetch merged PRs for a version range
const [diff, mergedPRs] = await pulls.getMergedPullRequests({
  owner: 'microsoft',
  repo: 'vscode',
  fromTag: {name: '1.80.0'},
  toTag: {name: '1.81.0'},
  includeOpen: false,
  failOnError: true,
  fetchViaCommits: false,
  fetchReviewers: true,
  fetchReleaseInformation: false,
  fetchReviews: true,
  mode: 'PR',
  configuration: config,
  includeOnlyPaths: null
})

console.log(`Version 1.81.0:`)
console.log(`  PRs: ${mergedPRs.length}`)
console.log(`  Commits: ${diff.commits}`)
console.log(`  Changes: +${diff.additions}/-${diff.deletions}`)

// Access individual PR data
for (const pr of mergedPRs.slice(0, 3)) {
  console.log(`  #${pr.number} - ${pr.title} (@${pr.author})`)
  if (pr.reviews && pr.reviews.length > 0) {
    console.log(`    Reviews: ${pr.reviews.map(r => r.author).join(', ')}`)
  }
}
```

--------------------------------

### JSON Configuration Example

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/configuration.md

An example of a JSON configuration object that can be provided as input. This allows for detailed customization of changelog generation, including category definitions and label handling.

```json
{
  "template": "#{{CHANGELOG}}\n\n<details>\n<summary>Uncategorized</summary>\n#{{UNCATEGORIZED}}\n</details>",
  "pr_template": "- [#{{NUMBER}}](PR_URL) - #{{TITLE}} (@#{{AUTHOR}})",
  "categories": [
    {
      "title": "## 🚀 Features",
      "labels": ["feature", "feat"],
      "exhaustive": false
    },
    {
      "title": "## 🐛 Bug Fixes",
      "labels": ["fix", "bug"],
      "exclude_labels": ["wontfix"]
    },
    {
      "title": "## 📦 Dependencies",
      "labels": ["dependencies"]
    },
    {
      "title": "## 📝 Uncategorized",
      "labels": []
    }
  ],
  "ignore_labels": ["ignore", "skip-changelog"],
  "transformers": []
}
```

--------------------------------

### Build Changelog Example

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-transform.md

Example usage of the buildChangelog function with sample parameters to generate changelog markdown.

```typescript
const changelog = buildChangelog(
  diffInfo,
  mergedPRs,
  {
    owner: 'owner',
    repo: 'repo',
    fromTag: {name: 'v1.0.0'},
    toTag: {name: 'v1.1.0'},
    mode: 'PR',
    configuration: config,
    includeOpen: false,
    failOnError: true,
    fetchReviewers: true,
    fetchReleaseInformation: false,
    fetchReviews: false,
    repositoryUtils: repository
  }
)
```

--------------------------------

### Install Dependencies and Run Linters

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/README.md

Install project dependencies using npm and run the linter with the fix flag to ensure code quality.

```bash
# Install the dependencies
$ npm install

# Verify lint is happy
$ npm run lint -- --fix
```

--------------------------------

### Changelog Structure Example

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-transform.md

Illustrates the hierarchical structure of the generated changelog, including global templates, category titles, and individual PR templates. This example shows a typical markdown output.

```markdown
# Changelog

## 🚀 Features
- [#123](https://github.com/owner/repo/pull/123) - Add new feature (@user1)
- [#124](https://github.com/owner/repo/pull/124) - Improve performance (@user2)

## 🐛 Bug Fixes
- [#125](https://github.com/owner/repo/pull/125) - Fix critical bug (@user3)

## 📦 Other Changes
- [#126](https://github.com/owner/repo/pull/126) - Update dependencies (@dependabot)
```

--------------------------------

### Configuration Merging Example

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/README.md

Shows how multiple configuration sources are merged, with JSON configuration taking precedence over file configuration, which in turn falls back to defaults.

```typescript
mergeConfiguration(jsonConfig, fileConfig, mode)
// Priority: JSON > File > Default
```

--------------------------------

### Dependency Injection Example

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/README.md

Demonstrates dependency injection in the ReleaseNotesBuilder class. Dependencies are passed via the constructor, facilitating testing with mocks.

```typescript
new ReleaseNotesBuilder(
  baseUrl,
  repositoryUtils,  // Injected - allows testing with mocks
  repositoryPath,
  // ... other params
)
```

--------------------------------

### Complex Configuration Example

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/README.md

Use this snippet for advanced configurations, specifying a JSON file for detailed settings. Ensure the `configuration` path is correct. The `token` is required for authentication.

```yaml
- name: "Complex Configuration"
  id: build_changelog
  if: startsWith(github.ref, 'refs/tags/')
  uses: mikepenz/release-changelog-builder-action@{latest-release}
  with:
    configuration: "configuration_complex.json"
    owner: "mikepenz"
    repo: "release-changelog-builder-action"
    ignorePreReleases: "false"
    fromTag: "0.3.0"
    toTag: "0.5.0"
    token: ${{ secrets.PAT }}
```

--------------------------------

### GiteaRepository Example Usage

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-repositories.md

Demonstrates how to instantiate GiteaRepository and use its methods to fetch tags and pull requests within a date range. Requires 'moment' for date handling.

```typescript
const gitea = new GiteaRepository(
  'gitea_token_xxx',
  'https://gitea.example.com',
  '/path/to/repo'
)

const tags = await gitea.getTags('owner', 'repo', 100)
const prs = await gitea.getBetweenDates(
  'owner',
  'repo',
  moment('2024-01-01'),
  moment('2024-01-31'),
  200
)
```

--------------------------------

### Path Filtering for Monorepos

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/configuration.md

Specify which paths to include or exclude when generating the changelog, useful for monorepo setups. This example shows how to include only specific directories.

```bash
# In GitHub Actions workflow:
- name: Build Changelog
  uses: mikepenz/release-changelog-builder-action@v6
  with:
    includeOnlyPaths: |
      src/core/
      docs/
```

--------------------------------

### Using Changelog Output in GitHub Release

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/github-actions-io.md

Example of how to use the 'changelog' output to populate the body of a GitHub release.

```yaml
- name: Create Release
  uses: softprops/action-gh-release@v1
  with:
    body: ${{ steps.build_changelog.outputs.changelog }}
```

--------------------------------

### Configuring Release Changelog Builder

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/github-actions-io.md

This example demonstrates how to configure the release-changelog-builder-action using a configuration file and specifying custom owner, repository, and tag information. It also shows how to fetch reviewers and release information.

```yaml
- name: Build Changelog
  id: changelog
  uses: mikepenz/release-changelog-builder-action@v6
  with:
    configuration: '.github/changelog-config.json'
    owner: 'my-org'
    repo: 'my-repo'
    fromTag: 'v1.0.0'
    toTag: 'v1.1.0'
    fetchReviewers: 'true'
    fetchReleaseInformation: 'true'
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Repository Pattern Example

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/README.md

Illustrates the repository pattern using `BaseRepository` for abstraction over Git platforms. It shows conditional instantiation of `OfflineRepository` or `GithubRepository`.

```typescript
const repo = offlineMode
  ? new OfflineRepository(path)
  : new GithubRepository(token, baseUrl, path)
```

--------------------------------

### Monorepo Configuration Example

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/README.md

Configure the action for monorepos by specifying paths to include. This allows generating changelogs for specific components within a larger project. The `token` is required.

```yaml
- name: "App1 Changelog"
  id: build_app1_changelog
  if: startsWith(github.ref, 'refs/tags/')
  uses: mikepenz/release-changelog-builder-action@{latest-release}
  with:
    includeOnlyPaths: |
      app1/
      shared/
    fromTag: "v1.0.0"
    toTag: "v2.0.0"
    token: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### OfflineRepository Example Usage

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-repositories.md

Demonstrates fetching tags and retrieving commit differences using the OfflineRepository. Assumes local git commands are available.

```typescript
const offline = new OfflineRepository('/path/to/repo')

// Fetches tags from local git
const tags = await offline.getTags('owner', 'repo', 100)

// Gets commits between refs using git CLI
const diff = await offline.getDiffRemote(
  'owner',
  'repo',
  'v1.0.0',
  'v1.1.0'
)
```

--------------------------------

### Changelog Builder with Custom Configuration

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/README.md

This example shows how to customize the changelog format using a JSON configuration. It defines a template and categories for organizing changelog entries.

```yml
jobs:
  release:
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest
    steps:
      - name: Build Changelog
        uses: mikepenz/release-changelog-builder-action@v6
        with:
          configurationJson: |
            {
              "template": "#{{CHANGELOG}}\n\n<details>\n<summary>Uncategorized</summary>\n\n#{{UNCATEGORIZED}}\n</details>",
              "categories": [
                {
                    "title": "## 💬 Other",
                    "labels": ["other"]
                },
                {
                    "title": "## 📦 Dependencies",
                    "labels": ["dependencies"]
                }
              ]
            }
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Basic Usage of Release Changelog Builder

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/github-actions-io.md

This snippet shows the basic setup for the release-changelog-builder-action in a GitHub Actions workflow. It checks out the code, builds the changelog, and then uses the output to create a GitHub release.

```yaml
name: Release Changelog

on:
  push:
    tags:
      - '*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build Changelog
        id: changelog
        uses: mikepenz/release-changelog-builder-action@v6
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          body: ${{ steps.changelog.outputs.changelog }}
```

--------------------------------

### Example Usage of PullRequestCollector.build()

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-pr-collector.md

Demonstrates how to instantiate and use the PullRequestCollector to build changelog data. It shows how to handle the returned data and log information about the collected pull requests and tags.

```typescript
const collector = new PullRequestCollector(
  null,
  repositoryUtils,
  '/repo',
  'owner',
  'repo',
  null,
  'v1.1.0',
  false,
  true,
  false,
  false,
  true,
  true,
  false,
  'PR',
  configuration,
  null
)

const data = await collector.build()
if (data) {
  console.log(`Found ${data.mergedPullRequests.length} PRs`)
  console.log(`From ${data.fromTag.name} to ${data.toTag.name}`)
}
```

--------------------------------

### Caching for Multiple Release Changelog Runs

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/github-actions-io.md

This example shows how to leverage caching with the release-changelog-builder-action for efficiency. The first step exports cache data, and subsequent steps use this cache to generate changelogs with different configurations.

```yaml
- name: Collect Data
  id: collect
  uses: mikepenz/release-changelog-builder-action@v6
  with:
    exportCache: 'true'
    exportOnly: 'true'
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

- name: Generate Changelog (Config A)
  uses: mikepenz/release-changelog-builder-action@v6
  with:
    cache: ${{ steps.collect.outputs.cache }}
    configurationJson: '{ ... }'

- name: Generate Changelog (Config B)
  uses: mikepenz/release-changelog-builder-action@v6
  with:
    cache: ${{ steps.collect.outputs.cache }}
    configurationJson: '{ ... }'
```

--------------------------------

### Get All Git Tags

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-utilities.md

Retrieves a list of all tags present in the Git repository. This can be used for comprehensive tag analysis.

```typescript
async getAllTags(): Promise<string[]>
```

--------------------------------

### Example Categorization Configuration

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-transform.md

This configuration defines how pull requests are categorized. It includes rules for labels, exclusion labels, and nested categories, along with flags for exhaustiveness and consumption.

```typescript
{
  title: "## Features",
  labels: ["feature", "feat"],
  exclude_labels: ["wontfix"],
  exhaustive: false,  // Any one label is enough
  consume: true,      // Exclude from later categories
  categories: [       // Nested sub-categories
    {
      title: "### Breaking Changes",
      labels: ["breaking"]
    }
  ]
}
```

--------------------------------

### Get Tags Method

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-commits.md

Fetches a specified number of tags from a given repository owner and name. Useful for retrieving all relevant tags for changelog generation.

```typescript
async getTags(
  owner: string,
  repo: string,
  maxTagsToFetch: number
): Promise<TagInfo[]>
```

--------------------------------

### Conventional Commits Configuration

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/configuration.md

Configure the action to parse commit messages following the Conventional Commits specification. This example maps commit types to changelog sections.

```json
{
  "mode": "COMMIT",
  "label_extractor": [
    {
      "pattern": "^(feat|fix|docs|style|refactor|perf|test|chore)",
      "on_property": "title",
      "target": "$1"
    }
  ],
  "categories": [
    { "title": "## Features", "labels": ["feat"] },
    { "title": "## Fixes", "labels": ["fix"] }
  ]
}
```

--------------------------------

### Example Template for PR Rendering

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-transform.md

This template defines the format for rendering individual pull requests in the changelog. It uses standard placeholders like PR number, title, and author.

```typescript
"- [#{{NUMBER}}]({{github_url}}/pull/#{{NUMBER}}) - #{{TITLE}} (@#{{AUTHOR}})"
```

--------------------------------

### Get Pull Requests Between Dates

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-pull-requests.md

Fetches merged pull requests within a specified date range. Requires repository owner, name, start and end dates, and a maximum number of pull requests.

```typescript
async getBetweenDates(
  owner: string,
  repo: string,
  fromDate: moment.Moment,
  toDate: moment.Moment,
  maxPullRequests: number
): Promise<PullRequestInfo[]>
```

--------------------------------

### Basic Release Notes Builder Usage

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-main.md

Demonstrates the basic initialization and usage of the ReleaseNotesBuilder.

```typescript
import {ReleaseNotesBuilder} from './releaseNotesBuilder.js'
import {GithubRepository} from './repositories/GithubRepository.js'
import {Configuration} from './configuration.js'

const config: Configuration = {
  // ... configuration options
}

const builder = new ReleaseNotesBuilder(
  null,
  new GithubRepository(token, undefined, '/path/to/repo'),
  '/path/to/repo',
  'owner',
  'repo',
  'v1.0.0',
  'v1.1.0',
  false,
  false,
  false,
  false,
  true,
  true,
  false,
  'PR',
  false,
  false,
  null,
  config,
  null
)

const changelog = await builder.build()
```

--------------------------------

### TagResult Data Structure

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-commits.md

Represents the result of a tag range resolution, indicating the start and end tags.

```typescript
interface TagResult {
  from: TagInfo | null
  to: TagInfo | null
}
```

--------------------------------

### Complete Configuration with Transformers

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-transform.md

Demonstrates a comprehensive configuration object for the Release Changelog Builder Action, showcasing the use of transformers to modify changelog content. This includes setting up categories, label extraction, and advanced text replacements for issue references.

```typescript
const config: Configuration = {
  template: '# Changelog\n\n#{{CHANGELOG}}',
  pr_template: '- [#{{NUMBER}}] #{{TITLE}}',
  categories: [
    {
      title: '## Breaking Changes',
      labels: ['breaking'],
      consume: true
    },
    {
      title: '## Features',
      labels: ['feature'],
      rules: [
        {
          pattern: '^feat',
          on_property: 'title'
        }
      ]
    }
  ],
  label_extractor: [
    {
      pattern: '^(feat|fix|docs)',
      target: '$1',
      method: 'match'
    }
  ],
  transformers: [
    {
      pattern: 'fixes #(\d+)',
      target: 'Fixes [#$1](https://github.com/owner/repo/issues/$1)',
      method: 'replaceAll'
    }
  ],
  custom_placeholders: [
    {
      name: 'TITLE_UPPER',
      source: 'TITLE',
      transformer: {
        pattern: '(.*)',
        target: '$1',
        method: 'replace',
        flags: 'i'
      }
    }
  ]
}

const changelog = buildChangelog(diffInfo, prs, {
  owner: 'owner',
  repo: 'repo',
  fromTag: {name: 'v1.0.0'},
  toTag: {name: 'v1.1.0'},
  mode: 'PR',
  configuration: config,
  includeOpen: false,
  failOnError: true,
  fetchReviewers: false,
  fetchReleaseInformation: false,
  fetchReviews: false,
  repositoryUtils: repository
})
```

--------------------------------

### Release Notes Builder Usage with Path Filtering

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-main.md

Demonstrates initializing the ReleaseNotesBuilder with path filtering to include only changes in specified directories or files.

```typescript
const builder = new ReleaseNotesBuilder(
  null,
  repository,
  '/repo',
  'owner',
  'repo',
  'v1.0.0',
  'v1.1.0',
  false,
  false,
  false,
  false,
  false,
  false,
  false,
  'PR',
  false,
  false,
  null,
  config,
  ['src/core/', 'README.md']  // Include only changes in these paths
)

const changelog = await builder.build()
```

--------------------------------

### Get Latest Git Tag

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-utilities.md

Retrieves the most recent tag in the Git repository. This is useful for identifying the latest release.

```typescript
async latestTag(): Promise<string>
```

--------------------------------

### Tags.retrieveRange

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-commits.md

Resolves the appropriate tag range for changelog generation, handling auto-resolution of start and end tags, filtering, and sorting.

```APIDOC
## retrieveRange()

### Description
Resolves the tag range for changelog generation. Core tag resolution logic.

### Method
`async`

### Parameters
#### Path Parameters
- **repositoryPath** (string) - Required - Local repository path
- **owner** (string) - Required - Repository owner
- **repo** (string) - Required - Repository name
- **fromTag** (string | null) - Optional - Starting tag (null for auto-resolve)
- **toTag** (string | null) - Optional - Ending tag (null for auto-resolve)
- **ignorePreReleases** (boolean) - Required - Skip pre-release tags when auto-resolving
- **maxTagsToFetch** (number) - Required - Maximum tags to fetch from API
- **tagResolver** (TagResolver) - Required - Tag resolution strategy (semver or sort)

### Returns
`Promise<TagResult>` - Object with `from` and `to` TagInfo (or null if resolution failed)

### Process
1. **Auto-resolve toTag:** If not provided, use `github.context.ref` or resolve as latest tag
2. **Auto-resolve fromTag:** If not provided, find predecessor tag using tag resolver
3. **Apply filters:** Filter tags by `tagResolver.filter` regex
4. **Apply transformers:** Transform tag names for sorting (if configured)
5. **Sort and match:** Find position of specified tag in sorted array
6. **Restore names:** Restore original tag names after sorting
```

--------------------------------

### Get Initial Git Commit

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-utilities.md

Retrieves the commit hash of the initial commit in the Git repository. Useful for establishing a baseline.

```typescript
async initialCommit(): Promise<string>
```

--------------------------------

### Get Git Tag Commit SHA

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-utilities.md

Retrieves the commit SHA associated with a specific Git tag. Requires the tag name.

```typescript
async getTagCommit(tagName: string): Promise<string>
```

--------------------------------

### BaseRepository Constructor

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-repositories.md

Initializes the repository with authentication token, API URL, and repository path. It also configures proxy settings from environment variables.

```typescript
protected constructor(
  protected token: string,
  protected url: string | undefined,
  protected repositoryPath: string
)
```

--------------------------------

### GiteaRepository Constructor

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-repositories.md

Initializes a GiteaRepository instance for interacting with the Gitea API.

```APIDOC
## Class: GiteaRepository

Gitea server API implementation.

### Constructor

```typescript
constructor(token: string, url?: string, repositoryPath: string)
```

#### Parameters

- **token** (string) - Required - Gitea API token
- **url** (string) - Optional - Gitea instance URL (e.g., `https://gitea.com`). Defaults to `https://gitea.com` if not specified.
- **repositoryPath** (string) - Required - Local repository path
```

--------------------------------

### Get Git Tag Creation Timestamp

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-utilities.md

Retrieves the creation timestamp for a specific tag in the Git repository. Requires the tag name as input.

```typescript
async tagCreation(tagName: string): Promise<string>
```

--------------------------------

### Resolve Repository Path

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-utilities.md

Resolves the repository path relative to the GitHub Actions workspace. Use this to get an absolute path for file operations.

```typescript
function retrieveRepositoryPath(providedPath: string): string
```

```typescript
const repoPath = retrieveRepositoryPath('./') // "/home/runner/work/repo/repo"
```

--------------------------------

### getDiff()

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-commits.md

Gets diff statistics and commit information between two refs, with deduplication. This method is useful for comparing changes between different versions of a repository.

```APIDOC
## getDiff()

### Description
Gets diff statistics and commit information between two refs, with deduplication.

### Method
GET

### Endpoint
(Not specified, assumed to be an SDK method)

### Parameters
#### Path Parameters
(None specified)

#### Query Parameters
(None specified)

#### Request Body
(None specified)

### Parameters
- **owner** (string) - Required - Repository owner
- **repo** (string) - Required - Repository name
- **base** (string) - Required - Base ref/tag
- **head** (string) - Required - Head ref/tag
- **includeOnlyPaths** (string[] | null) - Optional - Optional path patterns to filter commits

### Response
#### Success Response
- **DiffInfo** - Diff statistics and deduplicated commits
```

--------------------------------

### GiteaRepository Constructor

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-repositories.md

Initializes the GiteaRepository with an API token, the Gitea instance URL, and the local repository path.

```typescript
constructor(token: string, url: string | undefined, repositoryPath: string)
```

--------------------------------

### Extract Duplicate PRs by Ticket Number

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/configuration.md

Example JSON configuration for a duplicate filter using a regex to extract ticket numbers from PR titles.

```json
{
  "pattern": "#(\d+)",
  "on_property": "title",
  "target": "$1",
  "method": "match"
}
```

--------------------------------

### Run Tests and Debug

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/README.md

Execute the project's tests using npm. This command is also useful for debugging and testing changes locally.

```bash
# Run the tests, use to debug, and test it out
$ npm test
```

--------------------------------

### Derive New Placeholders from Existing Ones

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/README.md

Create custom placeholders by specifying a name, source placeholder, and a transformer. This example derives an uppercase author placeholder.

```typescript
{
  name: "AUTHOR_UPPERCASE",
  source: "AUTHOR",
  transformer: {
    pattern: "(.*)",
    target: "$1",
    flags: "i"
  }
}
```

--------------------------------

### GithubRepository Constructor

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-repositories.md

Initializes a GithubRepository instance for interacting with the GitHub or GitHub Enterprise API.

```APIDOC
## Class: GithubRepository

GitHub/GitHub Enterprise API implementation using Octokit REST client.

### Constructor

```typescript
constructor(token: string, baseUrl?: string, repositoryPath: string)
```

#### Parameters

- **token** (string) - Required - GitHub API token for authentication
- **baseUrl** (string) - Optional - GitHub Enterprise API URL (omit for public GitHub)
- **repositoryPath** (string) - Required - Local repository path
```

--------------------------------

### Configuration File Input

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/github-actions-io.md

Specify a JSON configuration file path. This is used if `configurationJson` is not provided.

```yaml
with:
  configuration: '.github/changelog.json'
```

--------------------------------

### transformStringToOptionalValue

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-utilities.md

Applies a regex transformer to a string and returns the first result or null if no match is found. This is a convenient way to get a single optional value from a string.

```APIDOC
## transformStringToOptionalValue()

### Description
Applies regex and returns first result or null.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **value** (string) - Required - Input string
- **extractor** (RegexTransformer) - Required - Compiled regex transformer

### Returns
`string | null` - First extracted value or null
```

--------------------------------

### Get Diff Between Refs

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-commits.md

Retrieves diff statistics and commit information between two specified Git references (tags or branches). Optionally filters commits by path.

```typescript
async getDiff(
  owner: string,
  repo: string,
  base: string,
  head: string,
  includeOnlyPaths?: string[] | null
): Promise<DiffInfo>
```

--------------------------------

### Configure Changelog Builder with JSON File

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/README.md

Reference an external JSON configuration file using the `configuration` input. Ensure a `checkout` step precedes this action to make the configuration file accessible.

```yaml
- name: "Build Changelog"
  uses: mikepenz/release-changelog-builder-action@{latest-release}
  with:
    configuration: "configuration.json"
```

--------------------------------

### Basic CI Workflow for Release Changelog

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/README.md

This workflow prepares a tag, builds a changelog, and creates a GitHub release. It uses the GITHUB_TOKEN for authentication.

```yml
name: 'CI'
on:
  push:
    tags:
      - '*'

jobs:
  release:
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest
    steps:
      - name: Build Changelog
        id: github_release
        uses: mikepenz/release-changelog-builder-action@v6
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Create Release
        uses: mikepenz/action-gh-release@v0.2.0-a03 #softprops/action-gh-release
        with:
          body: ${{steps.github_release.outputs.changelog}}
```

--------------------------------

### Example: Include Only Paths Input

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/github-actions-io.md

Use the `includeOnlyPaths` input to filter commits that modify specific files or directories. This is particularly useful for monorepos to generate package-specific changelogs.

```yaml
with:
  includeOnlyPaths: |
    src/core/
    docs/
    README.md
```

--------------------------------

### GithubRepository Constructor

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-repositories.md

Initializes the GithubRepository with an API token, an optional base URL for GitHub Enterprise, and the local repository path.

```typescript
constructor(token: string, baseUrl?: string, repositoryPath: string)
```

--------------------------------

### Resolve Configuration from File

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-utilities.md

Reads and parses configuration from a JSON file. Ensure the GitHub workspace path and configuration file path are correctly provided.

```typescript
function resolveConfiguration(
  githubWorkspacePath: string,
  configurationFile: string
): Configuration | undefined
```

```typescript
const config = resolveConfiguration('/repo', 'config/changelog.json')
if (config) {
  // Use config
}
```

--------------------------------

### Release Notes Builder Usage with Caching

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-main.md

Shows how to initialize the ReleaseNotesBuilder with cache export enabled. Cached data is available in GitHub Actions output.

```typescript
const builder = new ReleaseNotesBuilder(
  null,
  repository,
  '/repo',
  'owner',
  'repo',
  'v1.0.0',
  'v1.1.0',
  false,
  false,
  false,
  false,
  false,
  false,
  false,
  'PR',
  true,  // Enable cache export
  false,
  null,
  config,
  null
)

const changelog = await builder.build()
// Cached data available in GitHub Actions output 'cache'
```

--------------------------------

### Run Demo Test Locally

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/README.md

Execute the demo test file locally to test your own configuration and use-case. Modify the `__tests__/demo/demo.test.ts` file with your specific repository, token, and settings.

```bash
npm test -- -- demo.test.ts
```

--------------------------------

### Get Git Commits Between Refs

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-utilities.md

Retrieves detailed commit information between two specified Git refs (base and head). Supports optional filtering by file paths.

```typescript
async getCommitsBetween(
  base: string,
  head: string,
  includeOnlyPaths?: string[] | null
): Promise<{ count: number; commits: CommitInfo[] }>
```

--------------------------------

### Configuration JSON Input

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/github-actions-io.md

Pass changelog configuration directly as a JSON string. This takes precedence over a configuration file.

```yaml
with:
  configurationJson: |
    {
      "template": "#{{CHANGELOG}}",
      "categories": [
        {
          "title": "## Features",
          "labels": ["feature"]
        }
      ]
    }
```

--------------------------------

### ReleaseNotesOptions Interface

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-main.md

Defines the configuration and runtime options for the build pipeline.

```typescript
interface ReleaseNotesOptions {
  owner: string
  repo: string
  fromTag: TagInfo
  toTag: TagInfo
  includeOpen: boolean
  failOnError: boolean
  fetchReviewers: boolean
  fetchReleaseInformation: boolean
  fetchReviews: boolean
  mode: 'PR' | 'COMMIT' | 'HYBRID'
  configuration: Configuration
  repositoryUtils: BaseRepository
}
```

--------------------------------

### Get Commit History

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-commits.md

Retrieves the commit history between two resolved tags, including validation for backtrack time. This method is used for collecting commits for changelog generation.

```typescript
async getCommitHistory(options: Options): Promise<DiffInfo>
```

--------------------------------

### Get Open Pull Requests

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-pull-requests.md

Fetches currently open (unmerged) pull requests for a repository. Requires repository owner, name, and a maximum number of pull requests.

```typescript
async getOpen(
  owner: string,
  repo: string,
  maxPullRequests: number
): Promise<PullRequestInfo[]>
```

--------------------------------

### Exporting and Reusing Cache

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/github-actions-io.md

Demonstrates exporting the cache from one action run and reusing it in a subsequent run to maintain collected data.

```yaml
- name: Build Changelog
  id: build
  uses: mikepenz/release-changelog-builder-action@v6
  with:
    exportCache: true

- name: Build Alternative Changelog
  uses: mikepenz/release-changelog-builder-action@v6
  with:
    cache: ${{ steps.build.outputs.cache }}
    configurationJson: |
      {
        "template": "Alternative format",
        "categories": [...] 
      }
```

--------------------------------

### Cache Export and Import Workflow

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/README.md

Demonstrates the caching mechanism for exporting and importing collected data. Run 1 exports data to the cache, and Run 2 reuses this cached data to avoid API calls.

```bash
Run 1: exportCache=true → Exports collected data to cache
Run 2: cache=<path> → Reuses cached data, no API calls
```

--------------------------------

### Basic Changelog Generation

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/README.md

Use this snippet for a straightforward changelog generation on release. It requires the GITHUB_TOKEN environment variable.

```yaml
- name: Build Changelog
  uses: mikepenz/release-changelog-builder-action@v6
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Data Interface for Changelog Information

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-pr-collector.md

Represents the complete structure of the collected changelog data. It includes differential information, merged pull requests, and the resolved start and end tags.

```typescript
interface Data {
  diffInfo: DiffInfo
  mergedPullRequests: PullRequestInfo[]
  fromTag: TagInfo
  toTag: TagInfo
}
```

--------------------------------

### OfflineRepository Constructor

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-repositories.md

Initializes the OfflineRepository with the path to the local git repository.

```typescript
constructor(repositoryPath: string)
```

--------------------------------

### Get Pull Request Reviews

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-pull-requests.md

Fetches reviews for a given pull request and populates the 'reviews' field of the PR object in-place. Requires repository owner, name, and the PR object.

```typescript
async getReviews(
  owner: string,
  repo: string,
  pr: PullRequestInfo
): Promise<void>
```

--------------------------------

### Fetch Release Information

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/github-actions-io.md

When set to 'true', this option fetches release metadata such as creation date and draft status for the `fromTag` and `toTag`.

```yaml
with:
  fetchReleaseInformation: 'true'
```

--------------------------------

### Configure Gitea Platform in Workflow

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/README.md

Specify `platform: "gitea"` in your workflow file to use the action with Gitea. Ensure you provide a `GITEA_TOKEN` for authentication. The repository must be checked out as Gitea's API does not provide diff information.

```yaml
- name: Build Changelog
  uses: https://github.com/mikepenz/release-changelog-builder-action@v6
  with:
    platform: "gitea" # gitea or GitHub, default is GitHub
    configuration: "configuration.json"
    token: ${{ secrets.GITEA_TOKEN }}
```

--------------------------------

### Use Regex Transformers for Content Rewriting

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/README.md

Define regex transformers to rewrite content within changelogs. This example shows how to replace a pattern like 'fixes #(\d+)' with a GitHub issue link.

```typescript
{
  pattern: "fixes #(\d+)",
  target: "[Fixes #$1](https://github.com/org/repo/issues/$1)",
  method: "replaceAll"
}
```

--------------------------------

### GiteaRepository.fillTagInformation

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-repositories.md

Fetches and populates tag creation time information from the Gitea API.

```APIDOC
## Method: GiteaRepository.fillTagInformation

### Description

Fetches tag creation time from the Gitea API and populates this information.

### Method

(Implicitly called by the system, not directly invoked via HTTP)

### Endpoint

(Not applicable, uses Gitea API client)

### Parameters

(Refer to class constructor for initialization parameters)

### Response

(Details not specified in source, but implies returning tag information including creation time)
```

--------------------------------

### Example Usage: filterCommits with Exclusions

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-commits.md

Demonstrates how to use the filterCommits function by providing an array of strings to exclude commits whose summaries match patterns like 'Merge branch' or 'Merge pull request'.

```typescript
// Example: With excludeMergeBranches: ['Merge branch', 'Merge pull request'], commits with those strings in the summary are excluded.

```

--------------------------------

### resolveConfiguration

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-utilities.md

Reads and parses configuration from a JSON file. It requires the GitHub workspace path and the path to the configuration file.

```APIDOC
## resolveConfiguration()

### Description
Reads and parses configuration from a JSON file.

### Parameters
#### Path Parameters
- **githubWorkspacePath** (string) - Required - Workspace root path
- **configurationFile** (string) - Required - Relative path to configuration JSON file

### Returns
`Configuration | undefined` - Parsed config or undefined if file not found

### Example
```typescript
const config = resolveConfiguration('/repo', 'config/changelog.json')
if (config) {
  // Use config
}
```
```

--------------------------------

### Example Regex Transformer for Mentions

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-transform.md

This transformer rewrites GitHub mentions (e.g., '@username') into clickable links to user profiles. It uses a regular expression to find mentions and a target pattern to construct the link.

```typescript
{
  pattern: "@(\\w+)",
  target: "[@$1](https://github.com/$1)",
  method: "replaceAll"
}
```

--------------------------------

### Define Custom Placeholders in configuration.json

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/README.md

Use `custom_placeholders` in `configuration.json` to extract and insert custom values into templates. This example shows how to extract JIRA ticket IDs from the body and use them in both global and PR templates.

```json
{
  "template": "**Epics**\n#{{EPIC[*]}}\n\n#{{CHANGELOG}}",
  "pr_template": "- #{{TITLE}} - #{{URL}} #{{EPIC}}",
  "custom_placeholders": [
    {
      "name": "EPIC",
      "source": "BODY",
      "transformer": {
        "pattern": "[\\S\\s]*?(https:\/\/corp.atlassian.net\/browse\/EPIC-.{2,4})[\\S\\s]*",
        "target": "- $1"
      }
    }
  ]
}
```

--------------------------------

### Release Changelog Builder Action Data Flow

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/README.md

Illustrates the sequence of operations from GitHub Actions input to the final changelog output, including data collection, transformation, and rendering.

```text
GitHub Actions Input
    ↓
Configuration (JSON/File/Defaults)
    ↓
ReleaseNotesBuilder
    ├─ checkExportedData() [if cache provided]
    │
    ├─ PullRequestCollector
    │   ├─ Tags.retrieveRange() [resolve tags]
    │   ├─ Tags.fillTagInformation() [get release dates]
    │   └─ pullData()
    │       ├─ Commits.getCommitHistory() [diff stats]
    │       └─ PullRequests.getMergedPullRequests() [fetch PRs]
    │           └─ BaseRepository implementations
    │               ├─ GithubRepository (API calls)
    │               ├─ GiteaRepository (API calls)
    │               └─ OfflineRepository (git CLI)
    │
    ├─ writeCacheData() [if exportCache enabled]
    │
    └─ buildChangelog()
        ├─ Sort PRs
        ├─ Reference processing (parent-child)
        ├─ Deduplication
        ├─ Label extraction
        ├─ Regex transformers
        ├─ Categorization
        └─ Template rendering
            ↓
        Changelog Output
```

--------------------------------

### Build and Package for Distribution

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/README.md

Compile the TypeScript code and package it for distribution using npm scripts.

```bash
# Build the typescript and package it for distribution
$ npm run build && npm run package
```

--------------------------------

### Get Pull Requests for Commit Hash

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-pull-requests.md

Fetches pull requests associated with a specific commit SHA. Requires repository owner, name, commit SHA, and a maximum number of pull requests to retrieve.

```typescript
async getForCommitHash(
  owner: string,
  repo: string,
  commit_sha: string,
  maxPullRequests: number
): Promise<PullRequestInfo[]>
```

--------------------------------

### ReleaseNotesBuilder Constructor

Source: https://github.com/mikepenz/release-changelog-builder-action/blob/develop/_autodocs/api-reference-main.md

Initializes a new instance of the ReleaseNotesBuilder class. This constructor accepts numerous parameters to configure the changelog generation process, including repository details, tag ranges, and various fetching and filtering options.

```typescript
constructor(
  baseUrl: string | null,
  repositoryUtils: BaseRepository,
  repositoryPath: string,
  owner: string | null,
  repo: string | null,
  fromTag: string | null,
  toTag: string | null,
  includeOpen?: boolean = false,
  failOnError?: boolean,
  ignorePreReleases?: boolean,
  fetchViaCommits?: boolean = false,
  fetchReviewers?: boolean = false,
  fetchReleaseInformation?: boolean = false,
  fetchReviews?: boolean = false,
  mode?: 'PR' | 'COMMIT' | 'HYBRID' = 'PR',
  exportCache?: boolean = false,
  exportOnly?: boolean = false,
  cache?: string | null = null,
  configuration?: Configuration,
  includeOnlyPaths?: string[] | null = null
)
```