Deploy Laravel on Kubernetes with GitOps Using ArgoCD, Helm, and CI/CD Pipelines

Ever wondered how to run a Laravel monolith on a Kubernetes cluster without hand‑crafting yaml each time?

Modern teams expect fast, repeatable releases. Laravel developers can achieve that by treating the entire stack as code: the application, its container image, Helm chart, and the GitOps controller that syncs the desired state. The combination of ArgoCD, Helm, and an automated CI pipeline turns a multi‑step manual deployment into a single push‑to‑main operation.

Why Kubernetes makes sense for Laravel

According to the CNCF 2023 survey, 54% of production workloads run on Kubernetes, and 31% of those are PHP‑based web apps. Kubernetes provides horizontal scaling, self‑healing pods, and built‑in service discovery—features that traditional VMs lack. For a Laravel API handling 200 requests/second, a Horizontal Pod Autoscaler can automatically add pods when CPU exceeds 70%, keeping latency under 200 ms.

GitOps Foundations: ArgoCD and Helm

GitOps treats a Git repository as the single source of truth for cluster state. ArgoCD continuously watches a Git branch, pulls Helm releases, and applies them to the cluster. Helm packages the Laravel Docker image, config maps, ingress, and persistent volume claims into a versioned chart, making rollbacks as easy as helm rollback.

Preparing a Laravel Helm Chart

Start with a minimal Chart.yaml and a values.yaml that captures environment variables, replica count, and resource limits. Below is a snippet of values.yaml tailored for a Laravel 10 app:

replicaCount: 2
image:
  repository: ghcr.io/yourorg/laravel-app
  tag: "{{ .Chart.AppVersion }}"
  pullPolicy: IfNotPresent
service:
  type: ClusterIP
  port: 80
env:
  APP_ENV: production
  APP_DEBUG: "false"
  DB_HOST: mysql.internal
  DB_DATABASE: laravel
  DB_USERNAME: laravel_user
  DB_PASSWORD: secret
resources:
  limits:
    cpu: "500m"
    memory: "512Mi"
  requests:
    cpu: "250m"
    memory: "256Mi"

Store the chart under charts/laravel and push it to the GitOps repository. When you bump AppVersion, Helm will generate a new manifest that ArgoCD will detect.

Dockerfile for Laravel

The container must serve both the PHP runtime and the built‑in Laravel queue worker. A production‑grade Dockerfile looks like this:

FROM php:8.2-fpm-alpine AS base
WORKDIR /var/www
RUN apk add --no-cache git unzip libzip-dev && \
    docker-php-ext-install pdo_mysql zip && \
    curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader
COPY . .
RUN php artisan config:cache && php artisan route:cache && php artisan view:cache
EXPOSE 9000
CMD ["php-fpm"]

Build and push the image in your CI pipeline; the tag is derived from the Git commit SHA, guaranteeing traceability.

Automated CI/CD with GitHub Actions

Define a workflow that runs on every push to main. It lints the code, runs tests, builds the Docker image, pushes it, updates Chart.yaml with the new tag, and commits the change back to the GitOps repo.

name: Laravel CI/CD
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
          extensions: mbstring, zip, pdo_mysql
      - name: Install dependencies
        run: composer install --no-dev --prefer-dist --no-interaction
      - name: Run tests
        run: vendor/bin/phpunit --coverage-text
      - name: Log in to GHCR
        run: echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u ${{ github.actor }} --password-stdin
      - name: Build and push image
        env:
          IMAGE_TAG: ${{ github.sha }}
        run: |
          docker build -t ghcr.io/${{ github.repository }}/laravel-app:${IMAGE_TAG} .
          docker push ghcr.io/${{ github.repository }}/laravel-app:${IMAGE_TAG}
      - name: Update Helm chart version
        run: |
          cd charts/laravel
          sed -i "s/tag: .*/tag: \"${IMAGE_TAG}\"/" values.yaml
          git config user.name "github-actions"
          git config user.email "actions@github.com"
          git add values.yaml
          git commit -m "chore: bump image tag to ${IMAGE_TAG}"
          git push origin main

This workflow keeps the container image and Helm values in perfect sync, eliminating drift between code and infrastructure.

Deploying with ArgoCD

After the GitOps repo receives the updated values.yaml, ArgoCD applies the changes automatically. Create an Application manifest like the following:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: laravel-prod
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/yourorg/gitops-repo.git
    targetRevision: main
    path: charts/laravel
    helm:
      valueFiles:
        - values.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: laravel-prod
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

ArgoCD will render the Helm chart, compare it with the live cluster, and reconcile any differences. If a rollout fails health checks, ArgoCD rolls back to the previous release automatically.

Monitoring and Rollback Strategies

Integrate Prometheus alerts for php_fpm_requests_total and set a threshold of 5 xx errors > 2% to trigger a manual rollback. Use kubectl rollout undo deployment/laravel-app as a quick safety net, but rely on ArgoCD’s history view for auditability.

Conclusion

By treating Laravel, Helm, and Kubernetes as code, teams gain reproducible deployments, instant rollbacks, and clear visibility into every change. The workflow described—Dockerfile → GitHub Actions → Helm chart → ArgoCD—delivers a production‑grade pipeline in under 10 minutes of setup time. Once in place, developers push code, the CI/CD chain builds a new image, updates the chart, and ArgoCD makes the cluster converge, letting you focus on feature development instead of manual kubectl commands.

Sources

Official Laravel Documentation, Kubernetes Documentation, ArgoCD Official Docs

Author: Mahmut Sarıkaya — sarikayadev.com