intermediategeneral

How do you implement a CI/CD pipeline with GitHub Actions deploying to Kubernetes?

⚡

Quick Answer

A GitHub Actions CI/CD pipeline for Kubernetes typically runs lint and test jobs, builds a Docker image pushed to a container registry, updates Kubernetes manifests with the new image tag, and applies them using kubectl or a GitOps tool like ArgoCD. The pipeline uses environment protection rules for staged rollouts, OIDC for cloud authentication, and includes health checks and automated rollback on deployment failure.

Detailed Answer

Deploying to Kubernetes via GitHub Actions is like an assembly line in a car factory. Raw materials (source code) enter the line, go through quality inspection stations (lint, test, security scan), get assembled into a finished vehicle (Docker image), receive a VIN number (image tag), and roll off the line to the showroom (Kubernetes cluster). If a defect is found during the final road test (health check), the recall process (rollback) kicks in automatically. The entire line is automated, but certain checkpoints (environment approvals) require a human sign-off before the car ships to customers.

The pipeline structure follows a standard flow: source checkout, dependency installation, linting, unit and integration testing, Docker image build and push, manifest update, deployment, and verification. The Docker image is tagged with the git SHA for traceability — you can always trace a running container back to the exact commit that produced it. The image is pushed to a container registry (ECR, GCR, GHCR, or DockerHub), and then Kubernetes manifests are updated to reference the new image tag. For simple setups, kubectl directly applies the manifests. For mature teams, a GitOps approach commits the new image tag to a config repository that ArgoCD or Flux watches, providing an auditable deployment history and easy rollback via git revert.

Internally, the deployment step authenticates to the Kubernetes cluster using either a kubeconfig stored as a secret or, preferably, OIDC federation with the cloud provider's managed Kubernetes service (EKS, GKE, AKS). The workflow calls 'aws eks update-kubeconfig' or 'gcloud container clusters get-credentials' to configure kubectl. The deployment uses 'kubectl apply' or 'kubectl set image' to update the deployment resource, then 'kubectl rollout status' blocks until all pods are running the new version. Under the hood, Kubernetes performs a rolling update — creating new pods with the new image while gradually terminating old pods, maintaining availability throughout. The 'maxSurge' and 'maxUnavailable' settings in the deployment spec control the rollout speed and minimum availability.

Production pipelines add several critical layers. Environment protection rules in GitHub require manual approval before production deployments. Canary deployments route a small percentage of traffic to the new version before full rollout, using service mesh features or Kubernetes-native canary controllers. The pipeline includes a smoke test step that verifies critical endpoints return expected responses after deployment. If the smoke test fails, an automatic rollback step runs 'kubectl rollout undo'. Notifications via Slack or Teams inform the team of deployment status. For multi-cluster deployments (like deploying to regional clusters), a matrix strategy can parallelize the rollout across clusters while maintaining per-cluster health verification.

A key gotcha is using 'latest' as the Docker image tag — Kubernetes may not pull the new image if it sees the tag already exists locally due to imagePullPolicy defaults. Always use unique tags like the git SHA. Another trap is not setting resource limits in the Kubernetes deployment, causing the new pods to be evicted under memory pressure during rollout. The rollout status command can also time out silently if you do not set an explicit '--timeout' flag, making your pipeline appear to succeed when the deployment is actually stuck. Finally, ensure your service account has only the minimum RBAC permissions needed — a common mistake is granting cluster-admin to the CI service account, which violates least privilege and could be catastrophic if credentials are compromised.

# .github/workflows/order-service-k8s-deploy.yml # Complete CI/CD pipeline deploying order-service to Kubernetes name: Order Service K8s Deploy # Trigger on push to main on: # Run on pushes to main push: # Only the main branch branches: [main] # Only when relevant files change paths: ['src/**', 'Dockerfile', 'k8s/**', 'package*.json'] # Set minimum GITHUB_TOKEN permissions permissions: # Read repository contents contents: read # Required for OIDC token minting id-token: write # Allow writing packages to GHCR packages: write # Prevent concurrent deployments concurrency: # Group by workflow name group: deploy-order-service # Do not cancel in-progress deploys cancel-in-progress: false # Define all pipeline jobs jobs: # Job 1: Lint and static analysis lint: # Run on latest Ubuntu runs-on: ubuntu-latest # Lint steps steps: # Check out the code - uses: actions/checkout@v4 # Set up Node.js with caching - uses: actions/setup-node@v4 # Configure Node.js with: # Use Node.js 20 node-version: '20' # Enable npm caching cache: 'npm' # Install dependencies - run: npm ci # Name this step name: Install dependencies # Run ESLint across the project - run: npm run lint # Name this step name: Run ESLint # Run TypeScript type checking - run: npm run typecheck # Name this step name: TypeScript type check # Job 2: Run unit and integration tests test: # Run on latest Ubuntu runs-on: ubuntu-latest # Use PostgreSQL service container for integration tests services: # Define a PostgreSQL service postgres: # Use PostgreSQL 16 image image: postgres:16 # Set environment variables for the container env: # Set the database password POSTGRES_PASSWORD: testpass # Create the test database POSTGRES_DB: order_service_test # Map container port to host ports: # Map PostgreSQL default port - 5432:5432 # Health check to wait for PostgreSQL readiness options: >- --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5 # Test steps steps: # Check out the code - uses: actions/checkout@v4 # Set up Node.js - uses: actions/setup-node@v4 # Configure Node.js with: # Use Node.js 20 node-version: '20' # Enable npm caching cache: 'npm' # Install dependencies - run: npm ci # Name this step name: Install dependencies # Run unit tests with coverage - run: npm test -- --coverage # Name this step name: Run unit tests # Set database URL for integration tests env: # Connection string for the service container DATABASE_URL: postgresql://postgres:testpass@localhost:5432/order_service_test # Upload test coverage as artifact - uses: actions/upload-artifact@v4 # Configure artifact with: # Name the coverage artifact name: test-coverage # Upload coverage directory path: coverage/ # Job 3: Build and push Docker image build-image: # Depends on lint and test passing needs: [lint, test] # Run on latest Ubuntu runs-on: ubuntu-latest # Output the image tag for downstream jobs outputs: # Expose the full image reference image-ref: ${{ steps.meta.outputs.tags }} # Expose the image digest for verification digest: ${{ steps.build.outputs.digest }} # Build steps steps: # Check out the code - uses: actions/checkout@v4 # Set up Docker Buildx for advanced features - uses: docker/setup-buildx-action@v3 # Name this step name: Set up Docker Buildx # Login to GitHub Container Registry - uses: docker/login-action@v3 # Configure registry login with: # Use GitHub Container Registry registry: ghcr.io # Authenticate as the GitHub Actions bot username: ${{ github.actor }} # Use the GITHUB_TOKEN for authentication password: ${{ secrets.GITHUB_TOKEN }} # Generate Docker metadata (tags and labels) - uses: docker/metadata-action@v5 # Give this step an ID for output reference id: meta # Configure metadata generation with: # Target image name in GHCR images: ghcr.io/${{ github.repository }}/order-service # Generate tags: SHA, branch name, and latest tags: | type=sha,prefix=sha- type=ref,event=branch type=raw,value=latest,enable={{is_default_branch}} # Build and push the Docker image - uses: docker/build-push-action@v5 # Give this step an ID for digest output id: build # Configure the build with: # Use the repository root as context context: . # Push to the registry push: true # Apply the generated tags tags: ${{ steps.meta.outputs.tags }} # Apply the generated labels labels: ${{ steps.meta.outputs.labels }} # Use GitHub Actions cache for Docker layers cache-from: type=gha # Save layers to cache with max mode cache-to: type=gha,mode=max # Build for amd64 architecture platforms: linux/amd64 # Job 4: Deploy to staging deploy-staging: # Depends on image being built needs: build-image # Run on latest Ubuntu runs-on: ubuntu-latest # Target the staging environment environment: # Use the staging environment name: staging # Link to the staging URL url: https://staging.orders.example.com # Staging deploy steps steps: # Check out the code for K8s manifests - uses: actions/checkout@v4 # Authenticate to AWS using OIDC - uses: aws-actions/configure-aws-credentials@v4 # Configure OIDC auth with: # Assume the staging deploy role role-to-assume: ${{ secrets.AWS_STAGING_ROLE_ARN }} # Set the AWS region aws-region: us-east-1 # Configure kubectl for the staging EKS cluster - run: aws eks update-kubeconfig --name order-staging-cluster --region us-east-1 # Name this step name: Configure kubectl for staging # Update the image tag in the Kubernetes manifest - run: sed -i "s|IMAGE_TAG|sha-${GITHUB_SHA::7}|g" k8s/deployment.yml # Name this step name: Update manifest image tag # Apply the Kubernetes manifests - run: kubectl apply -f k8s/ # Name this step name: Apply K8s manifests to staging # Wait for the rollout to complete - run: kubectl rollout status deployment/order-service --timeout=300s # Name this step name: Wait for rollout completion # Run smoke tests against staging - run: | for i in 1 2 3 4 5; do STATUS=$(curl -s -o /dev/null -w '%{http_code}' https://staging.orders.example.com/health) if [ "$STATUS" = "200" ]; then echo 'Health check passed' && exit 0; fi sleep 10 done echo 'Health check failed after 5 attempts' && exit 1 # Name this step name: Smoke test staging deployment # Rollback if smoke test failed - if: failure() # Undo the last rollout on failure run: kubectl rollout undo deployment/order-service # Name this step name: Rollback staging on failure # Job 5: Deploy to production with approval deploy-production: # Depends on staging deployment succeeding needs: [build-image, deploy-staging] # Run on latest Ubuntu runs-on: ubuntu-latest # Target the production environment with protection rules environment: # Use the production environment (requires reviewers) name: production # Link to the production URL url: https://orders.example.com # Production deploy steps steps: # Check out the code - uses: actions/checkout@v4 # Authenticate to AWS using OIDC for production - uses: aws-actions/configure-aws-credentials@v4 # Configure OIDC auth for production with: # Assume the production deploy role role-to-assume: ${{ secrets.AWS_PROD_ROLE_ARN }} # Set the AWS region aws-region: us-east-1 # Configure kubectl for the production EKS cluster - run: aws eks update-kubeconfig --name order-prod-cluster --region us-east-1 # Name this step name: Configure kubectl for production # Update the image tag in the manifest - run: sed -i "s|IMAGE_TAG|sha-${GITHUB_SHA::7}|g" k8s/deployment.yml # Name this step name: Update manifest image tag # Apply manifests to production - run: kubectl apply -f k8s/ # Name this step name: Apply K8s manifests to production # Wait for production rollout with longer timeout - run: kubectl rollout status deployment/order-service --timeout=600s # Name this step name: Wait for production rollout # Comprehensive health check for production - run: | for endpoint in /health /health/db /health/cache; do STATUS=$(curl -s -o /dev/null -w '%{http_code}' "https://orders.example.com${endpoint}") if [ "$STATUS" != "200" ]; then echo "Failed: ${endpoint}" && exit 1; fi done echo 'All health checks passed' # Name this step name: Production health checks # Automatic rollback on any failure - if: failure() # Undo the deployment run: kubectl rollout undo deployment/order-service # Name this step name: Rollback production on failure # Notify team of successful deployment - if: success() # Send Slack notification run: | curl -X POST -H 'Content-type: application/json' \ --data '{"text":"order-service deployed to production: sha-'"${GITHUB_SHA::7}"'"}' \ ${{ secrets.SLACK_WEBHOOK_URL }} # Name this step name: Notify team via Slack

How do you implement a CI/CD pipeline with GitHub Actions deploying to Kubernetes?

More GitHub Actions questions