gen-aws-changelog

Generate changelogs by comparing commits between AWS CodePipeline stages for your GitHub repositories.

Overview

gen-aws-changelog is a CLI tool that fetches the current deployment state from AWS CodePipeline stages and generates a changelog showing all commits between two stages (e.g., staging and production). It uses the GitHub CLI to fetch commit information and compare revisions.

Prerequisites

Before using this tool, ensure you have:

1. GitHub CLI (gh) installed and authenticated

   # Install gh CLI (macOS)
   brew install gh
   
   # Authenticate
   gh auth login

2. AWS credentials configured with permissions to read CodePipeline state

   # Configure AWS credentials
   aws configure

   Required AWS permissions:

   • codepipeline:GetPipelineState
   • codepipeline:GetPipelineExecution

3. Node.js (version 20 or higher)

Installation

npm install -g @mindtwo/gen-aws-changelog

Usage

Basic Command

gen-aws-changelog <org/repo> --pipeline <pipeline-name> --fromStage <stage1> --toStage <stage2>

Example

gen-aws-changelog myorg/myrepo \
  --pipeline my-production-pipeline \
  --fromStage DeployStaging \
  --toStage DeployProduction \
  --region us-east-1

This will output:

### Changes for release DeployStaging (abc1234) to DeployProduction (def5678):

- abc1234 Fix authentication bug
- bcd2345 Add user profile feature
- cde3456 Update dependencies

Creating a GitHub Release

To automatically create a GitHub release with the changelog, add the --tag flag:

gen-aws-changelog myorg/myrepo \
  --pipeline my-production-pipeline \
  --fromStage DeployStaging \
  --toStage DeployProduction \
  --tag

This will:

• Create a GitHub release with a tag named release-DD-MM-YYYY (current date)
• Use the changelog as the release description
• Output the release URL

Command-Line Options

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | repo | positional | Yes | - | Repository name with organization/owner (e.g., owner/repo) | | --pipeline | string | No* | - | AWS CodePipeline name | | --fromStage | string | No* | - | Starting stage of the pipeline (e.g., DeployStaging) | | --toStage | string | No* | - | Ending stage of the pipeline (e.g., DeployProduction) | | --region | string | No | eu-central-1 | AWS region for CodePipeline | | --verbose | boolean | No | false | Enable verbose logging | | --quiet | boolean | No | false | Only show errors | | --noGit | boolean | No | false | Don't fetch repository configuration from GitHub | | --tag | boolean | No | false | Create a GitHub release with the changelog as description |

* Required unless configured in repository (see Git Repository Configuration below)

Git Repository Configuration

To avoid specifying pipeline configuration on every command, you can configure your repository with a .aws-changelog.json file. This file is automatically fetched from the default branch of your repository.

Configuration File

Create a file named .aws-changelog.json in the root of your repository:

{
  "pipeline": "my-production-pipeline",
  "region": "us-east-1",
  "fromStage": "DeployStaging",
  "toStage": "DeployProduction"
}

Configuration Schema

{
  "pipeline": string,     // CodePipeline name (optional)
  "region": string,       // AWS region (optional, defaults to eu-central-1)
  "fromStage": string,    // Starting stage name (optional)
  "toStage": string       // Ending stage name (optional)
}

Configuration Priority

The tool merges configuration from multiple sources in this order (later sources override earlier ones):

1. Default values
2. .aws-changelog.json from repository (if --noGit is not set)
3. Command-line arguments

Example with Repository Configuration

Once you've added .aws-changelog.json to your repository, you can run:

# Uses configuration from .aws-changelog.json
gen-aws-changelog myorg/myrepo

# Override specific options
gen-aws-changelog myorg/myrepo --toStage DeployCanary

Bypass Repository Configuration

Use --noGit to ignore the repository configuration file:

gen-aws-changelog myorg/myrepo --noGit \
  --pipeline different-pipeline \
  --fromStage Stage1 \
  --toStage Stage2

How It Works

1. Fetch Repository Config (optional): Uses gh CLI to fetch .aws-changelog.json from the repository's default branch
2. Query AWS CodePipeline: Fetches the current state of the specified pipeline stages
3. Extract Commit SHAs: Gets the Git commit SHAs deployed to each stage
4. Compare Commits: Uses gh CLI to compare commits between the two SHAs
5. Generate Changelog: Formats and displays the commit messages

Scripts

# Generate changelog
gen-aws-changelog myorg/myrepo --pipeline my-pipeline --fromStage Stage1 --toStage Stage2

Error Handling

The tool will exit with an error if:

• Repository name format is invalid (must be org/repo)
• Required configuration is missing
• AWS CodePipeline stages are not found
• GitHub repository is not accessible
• AWS credentials are not configured or lack permissions

Troubleshooting

"Stage not found in pipeline"

Ensure the stage names match exactly (case-sensitive) with your CodePipeline configuration.

# List pipeline stages
aws codepipeline get-pipeline-state --name your-pipeline-name

"Error fetching file from repository"

Ensure:

• gh CLI is authenticated (gh auth status)
• You have access to the repository
• The repository exists and the name is correct

AWS Permission Issues

Verify your AWS credentials have the required permissions:

aws codepipeline get-pipeline-state --name your-pipeline-name

License

MIT