Docker Helm Push

Flexibly build Docker images and/or package multiple Helm charts, then push them to a container registry — all in one simple GitHub Action

What Does It Do?

A single action that handles your complete container deployment pipeline

🐳

Docker Build

Multi-platform Docker builds with customizable build arguments and automatic secret injection

⎈

Helm Charts

Automatically packages all Helm charts in your directory with the same version and pushes to OCI registry

🏷️

Smart Tagging

Semantic version breakdown creates multiple tags (v1.2.3 → v1.2, v1) with suffix preservation

Build & Push Workflow

See how your code becomes deployed containers in Kubernetes

1
Push tag to repository
Triggers workflow with version: v1.2.3
2
Build Docker image
Creates multi-platform image: linux/amd64, linux/arm64
3
Push Docker image with tags
Pushes to registry: v1.2.3, v1.2, v1, latest
4
Package Helm chart
Creates chart package: my-app-1.2.3.tgz
5
Push Helm chart to OCI registry
Available at: oci://ghcr.io/owner/charts/my-app:1.2.3
6
Deploy to Kubernetes
Install with: helm install my-app oci://ghcr.io/owner/charts/my-app --version 1.2.3

Usage Examples

Get started quickly with these common configurations

🚀 Basic Usage

name: Build and Push

on:
  push:
    tags:
      - "v*"

jobs:
  build-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

      - name: Build and Push Docker with Helm
        uses: starburst997/docker-helm-push@v1
        with:
          image-name: my-app
          version: ${{ github.ref_name }}

🔧 Advanced with Build Arguments

name: Production Deploy

on:
  push:
    tags: ["v*"]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

      - name: Build and Push Docker with Helm
        uses: starburst997/docker-helm-push@v1
        with:
          image-name: my-app
          version: ${{ github.ref_name }}
          additional-tags: latest,stable
          version-breakdown: true
          platforms: linux/amd64,linux/arm64
          build-args: |
            [
              "NODE_ENV=production",
              "API_URL=https://api.example.com",
              "NPM_TOKEN=${{ secrets.NPM_TOKEN }}",
              "SENTRY_AUTH=${{ secrets.SENTRY_AUTH }}"
            ]

🎯 Complete CI/CD Pipeline

name: CI/CD Pipeline

on:
  push:
    branches: [main, develop]
    tags: ["v*"]
  pull_request:
    branches: [main]

jobs:
  build-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

      - name: Determine Version
        id: version
        run: |
          if [[ "${{ github.ref }}" == refs/tags/v* ]]; then
            # Production release
            echo "version=${{ github.ref_name }}" >> $GITHUB_OUTPUT
            echo "additional_tags=latest,stable" >> $GITHUB_OUTPUT
          elif [[ "${{ github.ref }}" == refs/heads/main ]]; then
            # Main branch build
            SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-7)
            echo "version=main-${SHORT_SHA}" >> $GITHUB_OUTPUT
            echo "additional_tags=latest" >> $GITHUB_OUTPUT
          else
            # Development build
            SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-7)
            echo "version=dev-${SHORT_SHA}" >> $GITHUB_OUTPUT
            echo "additional_tags=dev" >> $GITHUB_OUTPUT
          fi

      - name: Build and Push
        uses: starburst997/docker-helm-push@v1
        with:
          registry: ghcr.io
          image-name: my-application
          version: ${{ steps.version.outputs.version }}
          additional-tags: ${{ steps.version.outputs.additional_tags }}
          dockerfile: ./Dockerfile
          context: ./
          platforms: linux/amd64,linux/arm64
          helm-chart-path: charts
          push-helm: true
          version-breakdown: ${{ startsWith(github.ref, 'refs/tags/v') }}
          build-args: |
            [
              "BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ')",
              "VCS_REF=${{ github.sha }}",
              "VERSION=${{ steps.version.outputs.version }}",
              "NPM_TOKEN=${{ secrets.NPM_TOKEN }}"
            ]

Reference

Complete action inputs documentation

📥 Required Inputs

versionREQUIRED
Version tag for the image (e.g., v1.2.3, v1.2.3-dev)
Example: v1.2.3, main-abc123

⚙️ Optional Inputs

registry
Container registry URL
Default: ghcr.io
image-name
Name of the Docker image (optional)
Default: ${{ github.event.repository.name }}
username
Registry username or organization
Default: ${{ github.repository_owner }}
additional-tags
Additional tags to apply (comma-separated)
Default: latest
version-breakdown
Enable semantic version breakdown (v1.2.3 → v1.2, v1)
Default: true
make-public
Make packages public (ghcr.io only)
Default: false
platforms
Target platforms for multi-arch builds
Default: linux/amd64
token
GitHub token for authentication
Default: ${{ github.token }}
git-push
Push commits and tags to remote repository
Default: false

🐳 Docker Configuration

dockerfile
Path to the Dockerfile (skipped if not found)
Default: ./Dockerfile
context
Docker build context path
Default: ./
build-args
JSON array of build arguments and secrets
Example: ["NODE_ENV=production", "API_KEY=${{ secrets.API_KEY }}"]
cache
Enable Docker layer caching and Helm dependency caching for faster builds
Default: true

⎈ Helm Configuration

helm-chart-path
Path to directory containing Helm charts
Default: charts
push-helm
Whether to package and push Helm chart
Default: true
helm-strip-suffix
Strip version suffix for Helm charts (v1.2.3-dev becomes 1.2.3)
Default: true
app-version-strip-suffix
Strip version suffix for Docker app-version in Helm (v1.2.3-dev becomes v1.2.3)
Default: false
helm-namespace
Namespace for Helm charts in registry (e.g., 'charts' becomes '/charts')
Default: charts