In this tutorial, we'll build a modern CI/CD pipeline for Kubernetes applications using GitHub Actions, GitHub Container Registry, and ArgoCD. This represents a real-world GitOps workflow that many organizations use for deploying applications to Kubernetes.

What We'll Build

Our pipeline will have these components:

• GitHub Actions: Builds Docker images and updates deployment manifests

• GitHub Container Registry (GHCR): Stores our Docker images

• ArgoCD: Monitors our GitOps repository and deploys to Kubernetes

• Kubernetes: Runs our application

Prerequisites

• Docker Desktop with Kubernetes enabled

• Git installed

• GitHub account

• Basic understanding of Kubernetes, Docker, and YAML

New to Kubernetes? Check out our comprehensive Kubernetes Training course

Overview of the CI/CD Process

1. Developer pushes code to the application repository

2. GitHub Actions builds a Docker image and pushes it to GHCR

3. GitHub Actions updates the deployment manifest in the GitOps repository

4. ArgoCD detects the change and deploys the updated manifest to Kubernetes

Part 1: Setting Up the Application Repository

Fork the existing repository which already has the application code and configurations:

1. Go to https://github.com/rslim087a/kubernetes-cicd-tutorial

2. Click the "Fork" button in the top right corner

3. Wait for the repository to be forked to your GitHub account

The repository already contains a CI/CD workflow file at .github/workflows/ci-cd.yml. We will explore how the pipeline works very shortly. For now,

1. From the Github UI, navigate to .github/workflows/ci-cd.yml

2. Edit the file and look for these lines:

git clone https://github.com/rslim087a/grade-api-gitops.git gitops

...

3. Replace rslim087a with your GitHub username:

git clone https://github.com/YOUR_USERNAME/grade-api-gitops.git gitops

...

Part 4 will explain how the workflow works.

Part 2: Setting Up the GitOps Repository

Instead of creating a GitOps repository from scratch, fork the existing one:

1. Go to https://github.com/rslim087a/grade-api-gitops

2. Click the "Fork" button in the top right corner

3. Wait for the repository to be forked to your GitHub account

From the Github UI, update the deployment.yaml file to use your GitHub username:

# Change this line:
image: ghcr.io/rslim087a/kubernetes-cicd-tutorial:some_image_hash
# To use your username:

Part 3: Creating GitHub Personal Access Tokens

You'll need two Personal Access Tokens (PATs) for this tutorial. Let's create them one at a time:

Creating CR_PAT (Container Registry Token)

1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens

2. Click "Generate new token" → "Generate new token (classic)"

3. In the "Note" field, enter "Container Registry Access" (this is just for your reference)

4. Select the following scopes:

   • repo

   • write:packages

   • workflow

5. Click "Generate token"

6. IMPORTANT: Copy this token immediately and save it securely - you will only see it once!

Creating GITOPS_PAT (GitOps Repository Token)

1. Go back to GitHub → Settings → Developer Settings → Personal Access Tokens

2. Click "Generate new token" → "Generate new token (classic)" again

3. In the "Note" field, enter "GitOps Repository Access" (this is just for your reference)

4. Select the following scope:

   • repo

5. Click "Generate token"

6. IMPORTANT: Copy this token immediately and save it securely - you will only see it once!

You'll use these tokens in Part 5 when setting up GitHub Secrets. The secret names in your repository must be exactly "CR_PAT" and "GITOPS_PAT" to match what's referenced in the CI/CD workflow.

Part 4: Understanding the GitHub Actions Workflow

Let's understand the CI/CD workflow file at .github/workflows/ci-cd.yml.

CI/CD Pipeline Overview

This workflow is triggered whenever:

• Code is pushed to the main branch

• A pull request is created against the main branch

name: CI/CD Pipeline
on:
  push:
    branches: [ main ]
  pull_request:
    branches

Key Components of the Pipeline

1. Build and Push Steps:

jobs:
  build-and-push:
    runs-on: self-hosted
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v2
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.CR_PAT }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

      - name: Build and push Docker image
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: |
            ghcr.io/${{ github.repository }}:latest
            ghcr.io/${{ github.repository }}:${{ github.sha }}

• The pipeline runs on a self-hosted runner (runs-on: self-hosted)

• It checks out your code (actions/checkout@v3)

• Logs into GitHub Container Registry using your PAT (docker/login-action@v2 with secrets.CR_PAT)

• Sets up Docker Buildx for efficient builds (docker/setup-buildx-action@v2)

• Builds your Docker image and pushes it to GHCR with two tags (docker/build-push-action@v4):

  • latest - Always points to the most recent version

  • [commit-sha] - A unique tag based on the commit hash for versioning

2. GitOps Update Step:

- name: Update GitOps repository
  shell: bash
  env:
    GIT_TOKEN: ${{ secrets.GITOPS_PAT }}
  run: |
    # Configure git credential store
    git config --global credential.helper store
    echo "<https://${GIT_TOKEN}:x-oauth-basic@github.com>" > ~/.git-credentials

    # Remove any existing gitops directory
    rm -rf gitops

    # Clone repository using HTTPS URL without token
    git clone <https://github.com/rslim087a/grade-api-gitops.git> gitops
    cd gitops

    # Detect macOS and use appropriate sed command
    if [[ "$OSTYPE" == "darwin"* ]]; then
      sed -i '' "s|image: ghcr.io/${{ github.repository }}:.*|image: ghcr.io/${{ github.repository }}:${{ github.sha }}|g" deployment.yaml
    else
      sed -i "s|image: ghcr.io/${{ github.repository }}:.*|image: ghcr.io/${{ github.repository }}:${{ github.sha }}|g" deployment.yaml
    fi

    # Commit changes
    git config --global user.name "GitHub Actions"
    git config --global user.email "actions@github.com"
    git add deployment.yaml
    git commit -m "Update image to ${{ github.sha }}"

    # Push
    git push

• After pushing the image, the workflow updates your GitOps repository

• It uses your GITOPS_PAT to authenticate (env: GIT_TOKEN: ${{ secrets.GITOPS_PAT }})

• Clones your GitOps repository (git clone <https://github.com/rslim087a/grade-api-gitops.git> gitops)

• Updates the image tag in the deployment.yaml file to match the new commit SHA (sed -i "s|image: ghcr.io/...)

• Commits and pushes the change to your GitOps repository (git add, git commit, git push)

This is the "GitOps" part of the workflow - your application code repo automatically updates the deployment manifest in your infrastructure repo.

The pipeline ensures:

1. Every code change is containerized

2. Every container is uniquely tagged

3. Your deployment manifest is always updated to match your latest code

You'll need to add two secrets to your forked repository for this workflow to function, which we'll cover in Part 5.

Part 5: Setting Up GitHub Secrets

Add your PATs as secrets in your application repository:

1. Go to your application repository on GitHub

2. Click Settings → Secrets and variables → Actions

3. Click "New repository secret"

4. Create two secrets:

   • Name: CR_PAT, Value: your Container Registry PAT

   • Name: GITOPS_PAT, Value: your GitOps repository PAT

Part 6: Setting Up a Self-Hosted GitHub Actions Runner

To connect your local environment to GitHub Actions:

1. Go to your application repository on GitHub

2. Click Settings → Actions → Runners

3. Click "New self-hosted runner"

4. Select your operating system

5. Follow the instructions to download and configure the runner

6. Start the runner with ./run.sh (Unix) or run.cmd (Windows)

Keep this terminal window open as it will listen for and execute jobs.

Part 7: Creating Image Pull Secret

Before ArgoCD can deploy your application, you need to create a secret that allows Kubernetes to pull images from GitHub Container Registry:

kubectl create secret docker-registry ghcr-secret \\
  --docker-server=ghcr.io \\
  --docker-username=YOUR_GITHUB_USERNAME \\
  --docker-password=YOUR_CR_PAT \\
  --namespace

Important Notes:

• Use your GitHub username for YOUR_GITHUB_USERNAME

• Use the CR_PAT token you created earlier for YOUR_CR_PAT

• Even though the command uses "docker-registry" in its name, this is the standard Kubernetes secret type for all container registries, including GitHub Container Registry

• The secret must be named ghcr-secret as that's the name referenced in your deployment.yaml

This secret allows Kubernetes to authenticate with GitHub Container Registry to pull your private images. The deployment.yaml in your GitOps repository already includes a reference to this secret:

spec:
  template:
    spec:
      imagePullSecrets:
      - name

Part 8: Triggering Your First Build

Before setting up ArgoCD, let's trigger a build to make sure your image exists in GHCR:

1. Make a small change to your application code:

   # Add a comment to app.js
   echo "// Trigger CI/CD pipeline" >> src/app.js
   # Commit and push
   git add src/app.js
   git commit -m "Trigger CI/CD pipeline"
   git
   
   

2. Go to the Actions tab in your GitHub repository and confirm that the workflow runs successfully

3. Check that your image was pushed to GHCR under your account

Part 9: Installing ArgoCD in Your Kubernetes Cluster

Let's install and access ArgoCD in your Kubernetes cluster:

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update
kubectl create namespace argocd
helm install argocd argo/argo-cd --namespace argocd
kubectl port-forward svc/argocd-server -n argocd 8080

Get the initial password:

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

Access the ArgoCD UI at https://localhost:8080 with:

• Username: admin

• Password: (the output from the command above)

Part 10: Configuring ArgoCD to Deploy Your Application

In the ArgoCD UI, click "New App" and fill in these details:

• Application Name: grade-submission-api

• Project: default

• Sync Policy: Automatic

• Repository URL: https://github.com/YOUR_USERNAME/grade-api-gitops

• Revision: HEAD

• Path: .

• Cluster URL: https://kubernetes.default.svc

• Namespace: default

Click "Create"

Alternatively, you can create the application using kubectl:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: grade-submission-api
  namespace: argocd
spec:
  project: default
  source:
    repoURL: <https://github.com/YOUR_USERNAME/grade-api-gitops.git>
    targetRevision: HEAD
    path: .
  destination:
    server: <https://kubernetes.default.svc>
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Save this as argocd-application.yaml and apply it:

kubectl apply -f

Part 11: Testing the Complete Pipeline

Now let's test our CI/CD pipeline:

1. Make a change to your application code:

# Add a comment to app.js
echo "// Trigger CI/CD pipeline" >> src/app.js

# Commit and push
git add src/app.js
git commit -m "Trigger CI/CD pipeline"
git

1. Watch the GitHub Actions workflow run in your repository's Actions tab

2. Observe ArgoCD detecting and applying the changes

3. Check that your application is running:

kubectl get pods
kubectl port-forward svc/grade-submission-api 3000

1. Test your API:

# Get grades
curl <http://localhost:3000/grades>

# Add a grade
curl -X POST <http://localhost:3000/grades> \\
  -H "Content-Type: application/json" \\
  -d '{"name": "John Doe", "subject": "Math", "score": 95}'

How It All Works Together

Let's break down what happens when you push a change:

1. CI Phase (GitHub Actions):

   • GitHub Actions detects the push and runs your workflow

   • It builds a Docker image with your application code

   • It pushes the image to GitHub Container Registry with a unique tag

   • It updates the deployment manifest in your GitOps repository

2. CD Phase (ArgoCD):

   • ArgoCD continuously monitors your GitOps repository

   • When it detects a change, it compares the desired state with the current state

   • It applies the necessary changes to your Kubernetes cluster

   • Kubernetes pulls the new image and updates the running application

This represents a true GitOps approach, where:

• Git is the single source of truth

• All changes are declarative

• The system automatically converges to the desired state

Troubleshooting Tips

If you encounter issues with your pipeline:

1. ImagePullBackOff errors:

   • Check if your image is public or if you've configured image pull secrets correctly

   • Verify that the image tag in your deployment matches what was pushed

2. GitHub Actions failures:

   • Check your workflow logs for detailed error messages

   • Verify that your PATs have the correct permissions

3. ArgoCD sync issues:

   • Check the ArgoCD UI for sync errors

   • Verify that your GitOps repository is accessible to ArgoCD

Conclusion

You've now built a complete CI/CD pipeline for Kubernetes using GitHub Actions and ArgoCD! This represents a modern, GitOps approach to application deployment that many organizations are adopting.

By separating your application code from your deployment configuration, you've created a more maintainable and scalable system. The CI process updates both your application image and your deployment configuration, while the CD process automatically applies those changes to your cluster.

This pattern can be extended to support multiple environments, canary deployments, and other advanced deployment strategies.

Kubernetes Training

If you find these guides helpful, check out our Kubernetes Training course