About

Release software artifacts in AWS (S3, ECR, CodeArtifact) and NPM with consistent versioning!

⚠️ Feb 9, 2026 — version 5 was released to accommodate for breaking changes in NPM made back in Dec 9, 2025, see Migration Guide

You can release any combination of software packages, binary files, docker images, and raw repo files

This is especially useful in microservices where the release is a binary + IaC versioned via git tag

Features

• automatic and manual version generation
• release notes generation and changelog update
• floating tags — given the current version is 1.2.3 and you release 1.2.4 then also create/move tags 1.2, 1 and latest
• maintenance releases — made from branch like 1.x.x (given 2.x.x development is in main)
• prereleases — develop a next (often major, sometimes minor) version, typically made from a branch next
• dev-release — ability to publish artifacts for dev testing when testing on a local machine is impossible/complicated
• idempotency — ability to re-run the action without side effects
• GitHub release

Artifact types ⇔ features

| Artifact type | floating tags | idempotency | dev-release | auto cleanup | |---------------------------------------------------------------------------|---------------|-------------|-------------|--------------| | git | ✅ | ✅ | ✅ ️ | ✅ | | AWS S3 | ✅ | ✅ | ✅ | ✅ | | AWS ECR | ✅ | ✅ | ✅ | ✅ | | AWS CodeArtifact maven | ❌️ | ⚠️ | ❌️ | N/A | | npmjs | ✅ | ⚠️ | ❌️ | N/A |

See the respective artifact type to learn about idempotency limitations ⚠️

Usage

All examples are structured by artifact types and features

The example below shows how to publish binaries in S3:

name: Release

on:
  push: # note that 'pull_request' and 'pull_request_target' are not supported
    branches:
      - main

jobs:
  Release:
    runs-on: ubuntu-latest
    environment: release # has secret GH_TOKEN - a PAT with permission to bypass branch protection rule
    permissions:
      contents: read     # to checkout the code
      id-token: write    # to assume AWS role via OIDC
    steps:
      # (example) package AWS Lambda code as a zip archive in ./s3 directory
        
      - name: Release
        uses: agilecustoms/release@v5
        with:
          aws-account: ${{ vars.AWS_ACCOUNT_DIST }}
          aws-region: us-east-1
          aws-role: 'ci/publisher'
          aws-s3-bucket: 'mycompany-dist'
        env:
          GH_TOKEN: ${{ secrets.GH_TOKEN }}

Assume:

• you store artifacts in AWS account "Dist" and its number is stored in GH org variable AWS_ACCOUNT_DIST
• you have an S3 bucket mycompany-dist in us-east-1 region
• there is a role ci/publisher with permissions to upload files in this S3 bucket and trust policy that allows to assume this role from GH action
• you have repo mycompany/myapp
• current release branch main has a protection rule so all changes must be done via PR
• you have a GH environment release associated with branch main
• There is a PAT (Personal Access Token) with permission to bypass the branch protection rule. This PAT is stored as environment secret GH_TOKEN
• the latest tag is v1.2.3

Scenario:

• a developer made a feature branch and a commit with message feat: new-feature (alternatively use input version-bump for default minor/patch bump)
• the developer created and merged a PR which triggered a Release workflow
• build steps (omitted) produced a directory ./s3 with files (like a zip archive for AWS Lambda)

The action will:

• generate a new version v1.3.0 (minor bump based on commit message prefix feat:)
• upload files from ./s3 directory to S3 bucket mycompany-dist at path /myapp/v1.3.0/
• update CHANGELOG.md with release notes
• push tags v1.3.0, v1.3, v1 and latest to the remote repository
• create a GH Release tied to tag v1.3.0

Ecosystem

The action comes with an ecosystem:

• Terraform module to create a Release-ready GitHub repository
• Terraform modules to provide AWS policies to read and publish artifacts
• GitHub actions to use in build workflows, e.g., setup-maven-codeartifact
• documentation and examples for all supported artifact types
• Authorization and Security — how to make releases secure, including self-service (dev-releases)
• Release workflow best practices
• Articles: 🧩 Software distribution in AWS, 🧩 GitFlow vs Build-and-deploy

Inputs

There are no required inputs. The action only controls that the combination of inputs is valid

| Name | Default | Description | |-----------------------------|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | aws-account | | AWS account to publish artifacts to. Not needed if there are no artifacts, just a git tag | | aws-codeartifact-domain | | AWS CodeArtifact domain name, e.g., mycompany | | aws-codeartifact-repository | (see description) | AWS CodeArtifact repository name, e.g., maven. If aws-codeartifact-maven is set, then default to maven | | aws-codeartifact-maven | | Two possible values: build and publish. publish - publish maven artifacts to AWS CodeArtifact, build - just access CodeArtifact to update version in pom.xml | | aws-ecr | | If true, then push docker image to AWS ECR, example | | aws-region | | AWS region | | aws-role | | AWS IAM role to assume to publish, e.g., ci/publisher | | aws-s3-bucket | | AWS S3 bucket to upload artifacts to | | aws-s3-dir | | Allows you to specify AWS S3 bucket directory to upload artifacts to. By default, just place in bucket/{repo-name}/{version}/* | | changelog-file | CHANGELOG.md | Changelog file path. Pass an empty string to disable changelog generation | | changelog-title | # Changelog | Title of the changelog file (first line of the file) | | dev-branch-prefix |