GitHub Actions Kubernetes Pipeline#
This guide builds a complete pipeline: push code, build a container image, validate the Helm chart, and deploy to Kubernetes. Each stage gates the next, so broken images never reach your cluster.
Pipeline Overview#
The pipeline has four stages:
- Build and push the container image to GitHub Container Registry (GHCR).
- Lint and validate the Helm chart with
helm lint and kubeconform.
- Deploy to dev automatically on pushes to
main.
- Promote to staging and production via manual approval.
Complete Workflow File#
# .github/workflows/deploy.yml
name: Build and Deploy
on:
push:
branches: [main]
workflow_dispatch:
inputs:
environment:
description: "Target environment"
required: true
type: choice
options: [dev, staging, production]
env:
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }}
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
outputs:
image-tag: ${{ steps.meta.outputs.version }}
steps:
- uses: actions/checkout@v4
- name: Log in to GHCR
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Extract metadata
id: meta
uses: docker/metadata-action@v5
with:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
tags: |
type=sha,prefix=
type=ref,event=branch
- name: Build and push
uses: docker/build-push-action@v6
with:
context: .
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
validate:
runs-on: ubuntu-latest
needs: build
steps:
- uses: actions/checkout@v4
- name: Install Helm
uses: azure/setup-helm@v4
- name: Helm lint
run: helm lint ./charts/my-app -f charts/my-app/values.yaml
- name: Install kubeconform
run: |
curl -sL https://github.com/yannh/kubeconform/releases/latest/download/kubeconform-linux-amd64.tar.gz \
| tar xz -C /usr/local/bin
- name: Validate rendered templates
run: |
helm template my-app ./charts/my-app \
--set image.tag=${{ needs.build.outputs.image-tag }} \
| kubeconform -strict -summary \
-kubernetes-version 1.29.0
deploy-dev:
runs-on: ubuntu-latest
needs: [build, validate]
if: github.ref == 'refs/heads/main'
environment: dev
steps:
- uses: actions/checkout@v4
- name: Install Helm
uses: azure/setup-helm@v4
- name: Set up kubeconfig
run: |
mkdir -p ~/.kube
echo "${{ secrets.KUBECONFIG_DEV }}" | base64 -d > ~/.kube/config
chmod 600 ~/.kube/config
- name: Deploy with Helm
run: |
helm upgrade --install my-app ./charts/my-app \
--namespace my-app-dev \
--create-namespace \
-f charts/my-app/values-dev.yaml \
--set image.tag=${{ needs.build.outputs.image-tag }} \
--wait --timeout 300s
- name: Verify deployment
run: kubectl rollout status deployment/my-app -n my-app-dev --timeout=120s
deploy-staging:
runs-on: ubuntu-latest
needs: [build, validate, deploy-dev]
environment: staging
steps:
- uses: actions/checkout@v4
- name: Install Helm
uses: azure/setup-helm@v4
- name: Set up kubeconfig
run: |
mkdir -p ~/.kube
echo "${{ secrets.KUBECONFIG_STAGING }}" | base64 -d > ~/.kube/config
chmod 600 ~/.kube/config
- name: Deploy with Helm
run: |
helm upgrade --install my-app ./charts/my-app \
--namespace my-app-staging \
--create-namespace \
-f charts/my-app/values-staging.yaml \
--set image.tag=${{ needs.build.outputs.image-tag }} \
--wait --timeout 300s
deploy-production:
runs-on: ubuntu-latest
needs: [build, validate, deploy-staging]
environment: production
steps:
- uses: actions/checkout@v4
- name: Install Helm
uses: azure/setup-helm@v4
- name: Set up kubeconfig
run: |
mkdir -p ~/.kube
echo "${{ secrets.KUBECONFIG_PROD }}" | base64 -d > ~/.kube/config
chmod 600 ~/.kube/config
- name: Deploy with Helm
run: |
helm upgrade --install my-app ./charts/my-app \
--namespace my-app-prod \
--create-namespace \
-f charts/my-app/values-production.yaml \
--set image.tag=${{ needs.build.outputs.image-tag }} \
--wait --timeout 300s
Key Design Decisions#
Image Tagging with Git SHA#
The docker/metadata-action generates tags from the git SHA. This creates immutable, traceable image tags – you can always identify exactly which commit produced a given deployment.
