CI/CD Integration

Overview

AutoChangelog integrates with any CI/CD platform that can make HTTP requests. You add a step to your deployment pipeline that calls our webhook API after a successful deployment. This ensures your changelog is generated when changes actually go live, not just when they're merged.

Getting Your Webhook Credentials

Each repository has a unique webhook URL and secret. Find them on your Repositories page by clicking "Installation Instructions" on any enabled repository. You'll need both values: the URL to make requests to, and the secret to sign those requests for authentication.

GitHub Actions

GitHub Actions is the most common way to integrate AutoChangelog. First, add your webhook URL and secret as repository secrets in GitHub (Settings → Secrets and variables → Actions). Then add a step to your workflow that runs after deployment.

Here's a complete workflow that deploys and then generates a changelog:

name: Deploy and Changelog

on:
  push:
    branches: [main]

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

      - name: Deploy to production
        run: ./deploy.sh

      - name: Generate Changelog
        if: success()
        run: |
          BODY='{"bump": "patch"}'
          SIGNATURE="sha256=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "${{ secrets.AUTOCHANGELOG_SECRET }}" | cut -d' ' -f2)"
          curl -X POST "${{ secrets.AUTOCHANGELOG_WEBHOOK_URL }}" \
            -H "Content-Type: application/json" \
            -H "X-Webhook-Signature: $SIGNATURE" \
            -d "$BODY"

The if: success() condition ensures the changelog is only generated if deployment succeeds. You can change patch to minor or major depending on the type of release, or use a specific version number instead.

Using Git Tags for Versions

If you tag releases in Git, you can use the tag as your version number instead of auto-incrementing:

- name: Generate Changelog
  if: success()
  run: |
    VERSION=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
    if [ -n "$VERSION" ]; then
      BODY="{"version": "$VERSION"}"
    else
      BODY='{"bump": "patch"}'
    fi
    SIGNATURE="sha256=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "${{ secrets.AUTOCHANGELOG_SECRET }}" | cut -d' ' -f2)"
    curl -X POST "${{ secrets.AUTOCHANGELOG_WEBHOOK_URL }}" \
      -H "Content-Type: application/json" \
      -H "X-Webhook-Signature: $SIGNATURE" \
      -d "$BODY"

GitLab CI

For GitLab CI, add your webhook URL and secret as CI/CD variables (Settings → CI/CD → Variables), then add a job to your pipeline:

stages:
  - deploy
  - changelog

deploy:
  stage: deploy
  script:
    - ./deploy.sh

changelog:
  stage: changelog
  needs: [deploy]
  script:
    - |
      BODY='{"bump": "patch"}'
      SIGNATURE="sha256=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$AUTOCHANGELOG_SECRET" | cut -d' ' -f2)"
      curl -X POST "$AUTOCHANGELOG_WEBHOOK_URL" \
        -H "Content-Type: application/json" \
        -H "X-Webhook-Signature: $SIGNATURE" \
        -d "$BODY"
  only:
    - main

CircleCI

In CircleCI, add your credentials as environment variables in your project settings, then add a job:

version: 2.1

jobs:
  deploy:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - run:
          name: Deploy
          command: ./deploy.sh
      - run:
          name: Generate Changelog
          command: |
            BODY='{"bump": "patch"}'
            SIGNATURE="sha256=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$AUTOCHANGELOG_SECRET" | cut -d' ' -f2)"
            curl -X POST "$AUTOCHANGELOG_WEBHOOK_URL" \
              -H "Content-Type: application/json" \
              -H "X-Webhook-Signature: $SIGNATURE" \
              -d "$BODY"

workflows:
  deploy_and_changelog:
    jobs:
      - deploy:
          filters:
            branches:
              only: main

Other Platforms

Any CI/CD platform that can run shell commands will work. The pattern is always the same: compute an HMAC-SHA256 signature of your request body using your secret, then make a POST request with the signature in the X-Webhook-Signature header. See the Webhook API documentation for the complete API reference including examples in JavaScript and Python.

Best Practices

Always run the changelog step after your deployment step, not before. Use conditions to ensure it only runs on successful deployments. Store your webhook secret securely in your CI/CD platform's secrets or environment variables, never in your code. Check the HTTP response to make sure the request succeeded, and consider adding error handling to your scripts.

Troubleshooting

If your changelog isn't being generated, first check that your webhook URL and secret are correct by looking at the curl output in your CI logs. A 401 response means the signature is wrong, usually because the secret doesn't match. A 404 means the webhook URL is invalid or the repository is disabled. A 200 response saying "No new commits" means there's nothing new to document since your last entry. If you're still having trouble, check your changelog entries page in AutoChangelog for any entries in "needs review" status, which indicates the generation started but encountered an error.