Changesmith
Log inGet Started

CI/CD Integration

Automate changelog generation as part of your release workflow. Changesmith's CLI integrates with any CI/CD system that supports Node.js.

Setup

1. Generate an API Token

Generate an API token from the Changesmith dashboard. This token authenticates the CLI without interactive login.

2. Add the Token as a CI Secret

Add CHANGESMITH_TOKEN as a secret environment variable in your CI provider:

  • GitHub Actions: Settings > Secrets and variables > Actions > New repository secret
  • GitLab CI: Settings > CI/CD > Variables
  • CircleCI: Project Settings > Environment Variables

3. Configure Your Pipeline

The CLI detects CHANGESMITH_TOKEN automatically — no changesmith login step needed.

GitHub Actions

Generate and Update CHANGELOG.md

name: Generate Changelog
on:
  push:
    tags:
      - 'v*'

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Full history for tag detection

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Generate changelog
        env:
          CHANGESMITH_TOKEN: ${{ secrets.CHANGESMITH_TOKEN }}
        run: npx @changesmith/cli github ${{ github.ref_name }} -w

      - name: Commit CHANGELOG.md
        run: |
          git config user.name "github-actions"
          git config user.email "github-actions@github.com"
          git add CHANGELOG.md
          git commit -m "docs(changelog): update CHANGELOG.md for ${{ github.ref_name }}" || true
          git push

Generate and Publish a GitHub Release

- name: Generate and publish release
  env:
    CHANGESMITH_TOKEN: ${{ secrets.CHANGESMITH_TOKEN }}
  run: npx @changesmith/cli github ${{ github.ref_name }} --release

Do Both: CHANGELOG.md + GitHub Release

- name: Generate, update CHANGELOG.md, and publish release
  env:
    CHANGESMITH_TOKEN: ${{ secrets.CHANGESMITH_TOKEN }}
  run: npx @changesmith/cli github ${{ github.ref_name }} -w --release

Using Local Mode (No GitHub App)

If your repository isn't connected via the GitHub App, use the local command:

- name: Generate changelog (local)
  env:
    CHANGESMITH_TOKEN: ${{ secrets.CHANGESMITH_TOKEN }}
  run: npx @changesmith/cli local ${{ github.ref_name }} -w

GitLab CI

changelog:
  image: node:20
  stage: release
  only:
    - tags
  script:
    - npx @changesmith/cli github $CI_COMMIT_TAG -w --release
  variables:
    CHANGESMITH_TOKEN: $CHANGESMITH_TOKEN

CircleCI

version: 2.1
jobs:
  changelog:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Fetch full history
          command: git fetch --unshallow || true
      - run:
          name: Generate changelog
          command: npx @changesmith/cli github $CIRCLE_TAG -w --release
          environment:
            CHANGESMITH_TOKEN: ${CHANGESMITH_TOKEN}

workflows:
  release:
    jobs:
      - changelog:
          filters:
            tags:
              only: /^v.*/
            branches:
              ignore: /.*/

Important Notes

Full Git History

Most CI systems use shallow clones by default. Changesmith needs full history for tag detection:

# GitHub Actions
- uses: actions/checkout@v4
  with:
    fetch-depth: 0

# Other CI systems
git fetch --unshallow

github vs local in CI

| Feature | github | local | |---------|----------|---------| | Requires GitHub App | Yes | No | | PR/issue context | Yes | No | | --release flag | Yes | No | | Max commits | Unlimited | 500 | | Max diff size | Unlimited | 3 MB |

Use github when your repo is connected via the Changesmith GitHub App. Use local as a fallback when it isn't.

Token Security

  • Never commit tokens to version control
  • Use your CI platform's secrets management
  • Rotate tokens periodically from the dashboard

Next Steps