---
title: Configure changelogs
description: Before you can use the docs-builder changelog commands, you must evaluate your GitHub label strategy and verify that the necessary product metadata exists...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2927/contribute/configure-changelogs
products:
  - Elastic Docs Builder
---

# Configure changelogs
Before you can use the `docs-builder changelog` commands, you must evaluate your GitHub label strategy and verify that the necessary product metadata exists.
You can then set up a changelog configuration file to make the content workflow more automated and repeatable.

## Before you begin

1. Ensure that your products exist in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml). Products that only need release notes (not public documentation) can be added with `features: { public-reference: false }`. For more information, refer to [Products](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2927/configure/site/products).
2. Optional: Choose the GitHub labels that you'll use to automatically derive some changelog fields.
   1. Create labels for _types_. The supported types are defined in [ChangelogEntryType.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/ChangelogEntryType.cs). At a minimum, add labels for the `feature`, `bug-fix`, and `breaking-change` types.
2. Create labels for _products_. If your repo only pertains to a single product or you don't want to use labels to accomplish this classification, this step is not required.
3. Create labels for _areas_ (or "features" or "components") of your products. If you don't want to show categories (other than the default "type" categories) in your documentation, this step is not required.
4. Create labels to opt in or out of changelogs. For example, create `non-issue` or `release_notes:skip` labels for PRs that _shouldn't_ have changelogs. Alternatively, create a `@Public` label to identify PRs that _should_ have changelogs. You can only choose one label strategy for this behavior: exclusion or inclusion.
5. Create labels for _highlights_. This step is not required unless you want to publish release highlights.
3. If you'll be accessing GitHub from the command line, set up the necessary privileges as described in the following section.


### Authorization

Any of the `docs-builder changelog` commands that access GitHub require authority to view your pull requests and issues.
For example, this authority is required if you'll be running any of these [changelog commands](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2927/cli/changelog) from the command line: `changelog add`, `changelog bundle`, `changelog gh-release`.
You must log into GitHub or set the `GITHUB_TOKEN` (or `GH_TOKEN` ) environment variable with a sufficient personal access token (PAT) to pull information from your repository.
Otherwise, there will be fetch failures when you access private repositories and you might also encounter GitHub rate limiting errors.
For example, to create a new token with the minimum authority to read pull request details:
1. Go to **GitHub Settings** > **Developer settings** > **Personal access tokens** > [Fine-grained tokens](https://github.com/settings/personal-access-tokens).
2. Click **Generate new token**.
3. Give your token a descriptive name (such as "docs-builder changelog").
4. Under **Resource owner** if you're an Elastic employee, select **Elastic**.
5. Set an expiration date.
6. Under **Repository access**, select **Only select repositories** and choose the repositories you want to access.
7. Under **Permissions** > **Repository permissions**, set **Pull requests** to **Read-only**. If you want to be able to read issue details, do the same for **Issues**.
8. Click **Generate token**.
9. Copy the token to a safe location and use it in the `GITHUB_TOKEN` environment variable.


## Create a changelog configuration file

The changelog configuration file:
- Defines acceptable product, type, subtype, and lifecycle values.
- Sets default options, such as whether to extract issues and release note text from pull requests.
- Defines profiles for simplified bundle creation.
- Prevents the creation of changelogs when certain labels are present.
- Excludes changelogs from bundles based on their areas, types, or products.

<tip>
  Only one configuration file is required for each repository.
  You must maintain the file if your repo labels change over time.
</tip>

You can use the [changelog init](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2927/cli/changelog/init) command to create the changelog configuration file and folder structure automatically.
For example, run the following command in your GitHub repo's root directory:
```sh
docs-builder changelog init
```


## Review the settings

1. Find the configuration file.
   By default, the `changelog init` command creates `docs/changelog.yml`.
   If you move or rename this file, there will be extra steps when you configure its [usage](#usage).
2. Review the settings and update them based on your preferences.
   For descriptions of all the settings, refer to [Changelog configuration reference](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2927/contribute/configure-changelogs-ref).
   For example:
   - To limit the acceptable values, update [lifecycles](/elastic/docs-builder/pull/2927/contribute/configure-changelogs-ref#lifecycles) and [products](/elastic/docs-builder/pull/2927/contribute/configure-changelogs-ref#products).
- To set the changelog file name pattern, update [filename](/elastic/docs-builder/pull/2927/contribute/configure-changelogs-ref#filename).
- To control what is extracted from GitHub, update [extract](/elastic/docs-builder/pull/2927/contribute/configure-changelogs-ref#extract).
- To change bundle default behaviour or create reusable profiles, update [bundle](/elastic/docs-builder/pull/2927/contribute/configure-changelogs-ref#bundle).
- If you have GitHub labels to set changelog areas, types, or products, update [pivot](/elastic/docs-builder/pull/2927/contribute/configure-changelogs-ref#pivot).
- If you have GitHub labels to opt in or out of changelogs, update [rules.create](/elastic/docs-builder/pull/2927/contribute/configure-changelogs-ref#rules-create).
- If you want to filter changelogs in or out of release bundles based on their area, type, or products, update [rules.bundle](/elastic/docs-builder/pull/2927/contribute/configure-changelogs-ref#rules-bundle).

For example, a simple `docs/changelog.yml` looks like this:
```yml
filename: timestamp
products:
  available: []
extract:
  release_notes: true
  issues: true
  strip_title_prefix: false
lifecycles:
  - preview
  - beta
  - ga
pivot:
  types:
    breaking-change:
      labels: ">breaking, >bc"
    bug-fix: ">bug"
    feature:
```

For the most up-to-date changelog configuration options, refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml).

## Next steps

After you've created a config file, all subsequent changelog commands can use it.
By default, they look for `changelog.yml` by checking `./changelog.yml` then `./docs/changelog.yml` relative to your current directory.
Most changelog commands allow you to specify a different path with the `--config` option.
1. Start [creating changelog files](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2927/contribute/create-changelogs).
2. You might need to make further changes to your configuration file after you've performed a few tests. Likewise you might need to add bundle settings or profiles when you're ready to [create release bundles](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2927/contribute/bundle-changelogs).