I've been running a homelab Kubernetes cluster for a while now. It’s a simple two-node k3s setup with Traefik handling ingress and a Cloudflare Tunnel for external access. It’s been a great space to experiment and learn.

But deployment was still a pain.

Recently, I had a frontend app sitting in a GitLab repo, and every time I wanted to deploy, it turned into a small ritual. SSH into the server, pull the latest image, restart containers, and hope everything still worked. It got the job done, but it wasn’t something I trusted or enjoyed.

This post walks through how I moved from that setup to a full GitOps workflow using GitLab CI and ArgoCD. No prior ArgoCD experience, just figuring things out step by step until a simple `git push` became enough to deploy.

## The Starting Point

Going into this, my setup was pretty straightforward. I had a k3s cluster running on two Ubuntu nodes: one control plane and one worker, both on my local network. Traefik came bundled with k3s, so ingress was already handled. For external access, I was using a Cloudflare Tunnel running via `cloudflared` pods in a dedicated namespace, routing traffic from `*.demolamalomo.xyz` into the cluster.

The app itself was a frontend project. A Node.js app that builds into static files and gets served with nginx. The code lived in GitLab, and I was already using GitLab’s container registry to store images from earlier CI builds.

The CI pipeline, however, was doing too much. It built the image, then SSH-ed into the server to stop containers, remove them, pull new images, and restart everything. It worked most of the time, but it was fragile, hard to debug, and rolling back meant doing everything manually again.

## The Options I Considered

Throughout my deployment journey, I explored a couple of options before arriving at ArgoCD.

1. **Manual build and deploy** was basically what I was already doing. Build locally, push the image, run `kubectl apply`. The issue with this is that there’s no automation, no audit trail, and plenty of room for error.
2. **GitLab CI/CD handling everything** was the next step. The pipeline builds the image, pushes it, and deploys directly to the cluster using `kubectl`. This is where a lot of teams start, and honestly, it worked reasonably well for me too. But the CI was doing a lot of work, and it can get really messy with a lot of echoing and sshing commands. For context, below is a section of one of my CI build:

```bash
- echo "$ID_RSA_DEV_HOMELAB" > id_rsa_homelab
    - chmod 600 id_rsa_homelab
    - apk update && apk add openssh-client
    - echo "stop existing docker container & remove images"
    - echo "Port $STAGE_SVR_PORT_HOMELAB"
    - echo "User $DEV_SERVER_USER_HOMELAB"
    - echo "Host $STAGE_SVR_IP_HOMELAB"
    - echo "VM $STAGE_VM_IP_HOMELAB"
    - echo "Service $SERVICE_NAME_HOMELAB"
    - ssh -i id_rsa_homelab -p $STAGE_SVR_PORT_HOMELAB -o StrictHostKeyChecking=no $DEV_SERVER_USER_HOMELAB@$DEV_SVR_IP_HOMELAB "docker stop $SERVICE_NAME_HOMELAB || true"
......
```

3. **GitOps with ArgoCD** takes a different approach. CI still builds and pushes images, but it never talks to the cluster directly. Instead, it updates a Git repo that contains the Kubernetes manifests. ArgoCD, running inside the cluster, watches that repo and syncs any changes.The thing I liked most was that I could look at a repository and immediately know what should be running in the cluster.

That was the point where ArgoCD clicked for me. I liked the fact that I could open a repo and know exactly what was deployed. Rollbacks also become much simpler, by just reverting a commit. So I went with **ArgoCD**.

## Installing ArgoCD

I’d never used ArgoCD before, so this part was new. Thankfully, installation was straightforward:

```bash
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
```

After a minute or so, everything was running, and I could start exploring the dashboard.

To access the dashboard, I started with a simple port-forward:

```bash
kubectl port-forward svc/argocd-server -n argocd 8080:443
```

The default login is `admin`, and the initial password is stored in a Kubernetes secret:

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

I also installed the ArgoCD CLI, which made it easier to create applications and debug sync issues without constantly switching to the browser.

Later on, I exposed ArgoCD through Traefik and my Cloudflare Tunnel so I could access it remotely, but the port-forward was more than enough to get started.

![ArgoCD UI](https://paper-attachments.dropboxusercontent.com/s_2A415A66514362A902F36E27BA0662B25C280357D4A31FB4FA73DA4B634FE1E6_1775396935665_Screenshot+2026-04-05+at+14.48.16.png)

## Understanding the Two-Repo Pattern

One thing that took me a while to wrap my head around was the idea of maintaining two repositories. At first it felt unnecessary. Why split things up when everything belongs to the same application?

But after working with it for a bit, the separation started to make sense.

The **application repo** is where development happens. Code changes, Dockerfile, and CI configuration (`.gitlab-ci.yml`).

The **GitOps repo** is different. Its only job is to describe what's running in the cluster. Deployments, Services, and Ingress definitions. ArgoCD watches this repo and syncs the cluster whenever something changes.

The benefit became obvious pretty quickly. My application repo changes all the time with feature work, bug fixes, and random experiments, while the GitOps repo changes much less often because it only reflects what should be running in the cluster.

![ArgoCD workflow](https://paper-attachments.dropboxusercontent.com/s_2A415A66514362A902F36E27BA0662B25C280357D4A31FB4FA73DA4B634FE1E6_1775397646668_mermaid-diagram.png)

My GitOps repo (`homelab-gitops`) ended up looking like this:

```bash
homelab-gitops/
  clohea-admin/   # my application folder
    deployment.yaml
    service.yaml
    ingress.yaml
```

## Setting up the GitLab CI Pipeline

My existing `.gitlab-ci.yml` was doing too much. The new version only needed to do two things: build the image and update the GitOps repo.

The build stage pushes two tags:

- `:latest` for general use
- a commit hash tag like `:a1b2c3d`, which is what goes into the manifests

That commit-specific tag is important because it gives ArgoCD a concrete change to detect.

```yaml
docker-build-homelab-dev:
    image: docker:latest
    stage: build
    services:
        - docker:dind
    before_script:
        - echo $CI_JOB_TOKEN | docker login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY
    script:
        - echo "$DEV_ENV" > $CI_PROJECT_DIR/.env
        - docker build -f ./Dockerfile --pull -t "$CI_REGISTRY_IMAGE:latest" -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
        - docker push "$CI_REGISTRY_IMAGE:latest"
        - docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
    only:
        - homelab-dev
```

The deploy stage updates the GitOps repo:

```yaml
update-manifest:
    stage: deploy
    image: alpine:latest
    before_script:
        - apk add --no-cache git sed
        - git config --global user.email "ci@gitlab.com"
        - git config --global user.name "GitLab CI"
    script:
        - git clone https://deploy-token:${GITOPS_TOKEN}@gitlab.com/clohea-fe/homelab-gitops.git
        - cd homelab-gitops
        - 'sed -i "s|image: .*|image: ${CI_REGISTRY_IMAGE}:${CI_COMMIT_SHORT_SHA}|" clohea-admin/deployment.yaml'
        - git add .
        - git diff --cached --quiet && echo "No changes" || git commit -m "Update frontend image to $CI_COMMIT_SHORT_SHA" && git push
    only:
        - homelab-dev
```

One thing that tripped me up: the `sed` command needs to use double quotes so that the shell expands the CI variables. My first attempt used single quotes, which meant `$CI_REGISTRY_IMAGE` was treated as literal text. The `sed` command found nothing to replace, `git commit` found nothing to commit, and the pipeline failed with `exit code 1`. A small thing, but the kind of mistake that costs you 30 minutes of staring at logs.

**A Note on the GITOPS_TOKEN**
The `update-manifest` job needs write access to the GitOps repo. I created a **Project Access Token** in the GitOps repo (Settings > Access Tokens) with `write_repository` scope, then stored it as a CI/CD variable called `GITOPS_TOKEN` in the app repo (Settings > CI/CD > Variables), with the "Mask variable" option checked so it doesn't leak into logs.

I could also have used a Personal Access Token, which would work across all my repositories, but a Project Access Token scoped to just the GitOps repo is cleaner from a security standpoint.

## The Kubernetes Manifests

The GitOps repo itself stayed pretty simple. For this application, I only needed three manifests:

- A Deployment
- A Service
- An Ingress

Nothing fancy. Just enough to get the application running and exposed through Traefik.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
    name: webapp-service
    namespace: frontend
spec:
    replicas: 2
    selector:
        matchLabels:
            app: webapp-service
    template:
        metadata:
            labels:
                app: webapp-service
        spec:
            imagePullSecrets:
                - name: gitlab-registry-cred
            containers:
                - name: webapp-service
                  image: registry.gitlab.com/clohea-fe/clohea-admin/webapp-service:INITIAL_TAG
                  ports:
                      - containerPort: 3000
```

Since the registry is private, I created an image pull secret:

```bash
kubectl create secret docker-registry gitlab-registry-cred \
  --namespace frontend \
  --docker-server=registry.gitlab.com \
  --docker-username=<deploy-token-username> \
  --docker-password=<deploy-token-value>
```

The service routes traffic internally:

```yaml
apiVersion: v1
kind: Service
metadata:
    name: webapp-service
    namespace: frontend
spec:
    selector:
        app: webapp-service
    ports:
        - port: 80
          targetPort: 3000
```

And the ingress exposes it via Traefik:

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
    name: webapp-service
    namespace: frontend
spec:
    ingressClassName: traefik
    rules:
        - host: admin-portal.demolamalomo.xyz
          http:
              paths:
                  - path: /
                    pathType: Prefix
                    backend:
                        service:
                            name: webapp-service
                            port:
                                number: 80
```

## Connecting ArgoCD to the GitOps Repo

For ArgoCD to watch the GitOps repo, it needs credentials since it's a private GitLab repo. I created a deploy token in the GitOps repo with `read_repository` scope, then added the repo to ArgoCD using the UI.

**Settings > Repositories > + CONNECT REPO**

![Add repository to ArgoCD](https://paper-attachments.dropboxusercontent.com/s_2A415A66514362A902F36E27BA0662B25C280357D4A31FB4FA73DA4B634FE1E6_1775418533445_Screenshot+2026-04-05+at+20.48.03.png)

Another option to do this is to use the CLI:

```bash
argocd repo add https://gitlab.com/clohea-fe/homelab-gitops.git \
  --username <deploy-token-username> \
  --password <deploy-token-value>
```

Then I created the application by entering the repository URL, the path to the application folder in the GitOps repo, and a few other required settings.

**Application > + NEW APP**

![New App](https://paper-attachments.dropboxusercontent.com/s_2A415A66514362A902F36E27BA0662B25C280357D4A31FB4FA73DA4B634FE1E6_1775418812700_Screenshot+2026-04-05+at+20.51.21.png)

I can also use the CLI by running the command below

```bash
argocd app create frontend \
  --repo https://gitlab.com/clohea-fe/homelab-gitops.git \
  --path clohea-admin \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace frontend \
  --sync-policy automated \
  --auto-prune \
  --self-heal
```

Quick breakdown of the flags:

- `--sync-policy automated`: syncs on every commit
- `--auto-prune`: removes deleted resources
- `--self-heal`: reverts manual cluster changes

## The Debugging Marathon

If I'm being honest, the setup didn't just work on the first try. Here's a condensed version of the issues I hit, because I think they're genuinely useful for anyone doing this for the first time.

**Image pull errors.** The first deployment failed with a `403 Forbidden` because Kubernetes couldn't authenticate with GitLab's private container registry. The fix was creating the `docker-registry` secret and adding `imagePullSecrets` to the deployment manifest. Then it failed again with `not found` — the image tag referenced in the manifest didn't exist in the registry because my build job hadn't pushed a commit-hash tag yet.

**Name mismatches.** My ingress was referencing a service called `frontend`, but the actual service was named `webapp-service`. A simple typo that resulted in a 502 from Traefik. `kubectl describe ingress` made this obvious once I thought to look.

**Port mismatch.** This one was subtle. The deployment had `containerPort: 80` and the service was targeting port 80, but nginx inside the container was actually listening on port 3000. The Docker image had a custom nginx config that bound to 3000 instead of the default 80. Running `kubectl exec` and checking `netstat -tlnp` inside the pod revealed the mismatch immediately.

## The End Result

Once everything was wired up and the bugs were resolved, the flow became exactly what I wanted:

- I push code to the `homelab-dev` branch.
- GitLab CI builds the Docker image and pushes it to the registry with both a `:latest` and a commit-hash tag.
- The `update-manifest` job clones the GitOps repo, updates the image tag in the deployment manifest, and pushes.
- ArgoCD detects the new commit within seconds.
- ArgoCD syncs the manifests to the cluster, Kubernetes pulls the new image, and the app is live.

The ArgoCD dashboard shows the full picture. Sync status, pod health, the Git commit that triggered the deployment. If something goes wrong, I can see exactly which commit caused it and revert.

![ArgoCD Dashboard](https://paper-attachments.dropboxusercontent.com/s_2A415A66514362A902F36E27BA0662B25C280357D4A31FB4FA73DA4B634FE1E6_1775420456749_Screenshot+2026-04-05+at+21.19.00.png)

The entire deployment chain is now traceable through Git commits. No more SSH-ing into servers or chained server commands. Just `git push`, and everything takes care of itself.


I got tired of SSH-ing into servers every time I needed to deploy a simple app. So I spent an evening setting up GitLab CI, ArgoCD, and a GitOps workflow in my homelab. Here's what worked, what broke, and what I learned along the way.

#CI/CD

From Manual Deploys to GitOps: How I Automated my Homelab with ArgoCD and GitLab CI