gear-foundation/argocd-workflow: The Synchronous Contract for GitOps
Moving beyond "fire and forget" deployments with centralized gatekeeping and real-time health loops.
- A centralized gatekeeper pattern allows DevOps teams to pause or enable deployments globally via a single configuration file.
- The workflow eliminates false success signals by polling the ArgoCD CLI until the application reaches a Healthy state.
- Programmatic manifest mutation replaces external image updaters to ensure direct synchronization between the registry and the cluster.
- Reusable GitHub Actions workflows provide a versioned deployment standard that scales across dozens of microservices.
The Green Checkmark Fallacy
The "magic" of GitOps often hides a frustrating reality. A developer pushes code, GitHub Actions reports a triumphant green checkmark, and everyone moves on to the next task. Meanwhile, deep in the Kubernetes cluster, a pod is crash-looping due to a misconfigured environment variable.
This disconnect happens because standard CI/CD pipelines treat the handoff to GitOps as a "fire and forget" operation. They update a manifest, push it to a repository, and immediately declare victory. The pipeline has no idea if the deployment actually succeeded in the real world.
The gear-foundation/argocd-workflow repository was built to fix this false positive. It treats the boundary between Continuous Integration and Continuous Deployment not as a blind handoff, but as a synchronous contract.
The Global Kill-Switch
Most pipelines trigger blindly on every code push. This workflow introduces a "Gatekeeper" pattern. Before any image is built or any infrastructure is mutated, the pipeline pauses to consult a centralized registry.
By checking an applications.yaml file in a separate, dedicated GitOps repository, DevOps teams can globally pause or enable deployments for specific microservices across specific environments. This means a deployment freeze can be enacted instantly without ever touching the application's source code.
Smart environment detection (`dev`, `stg`, `prod`) based on branch name
Mutating the Truth
Once the gatekeeper approves the deployment, the workflow builds the image and pushes it to the GitHub Container Registry. But the most critical work happens during the manifest update phase.
Instead of relying on external automation tools like Argo Image Updater, the workflow acts as a GitOps bot. It clones the target infrastructure repository and uses yq to programmatically inject the new image tag directly into the correct environment's Helm values.yaml file.
Crucially, the pipeline then refuses to exit. It calls the ArgoCD CLI to force an immediate sync and actively polls the cluster. It waits until the application reaches a "Healthy" state before passing the final success signal back to GitHub, completely eliminating the green checkmark fallacy.
Scale via Reusability
Maintaining custom deployment scripts across dozens of microservices is an operational nightmare. The Gear Foundation designed this tool as a "Workflow-as-a-Service" to abstract away that complexity.
This **reusable GitHub Actions workflow** builds your Docker image, updates ArgoCD Helm values, and triggers deploy.
By utilizing GitHub's workflow_call pattern, organizations can enforce a single, versioned deployment standard across all their repositories. If the deployment logic needs to change—for example, adding a new security scanning step—it only needs to be updated in one central location.
| Feature | Standard CI Push | gear-foundation Workflow |
|---|---|---|
| Trigger | Unconditional on push | Gated by central applications.yaml |
| Completion Signal | Manifest committed to Git | Pods reported Healthy by ArgoCD |
| Failure Visibility | Buried in GitHub Actions logs | Integrated Telegram alerts |
| Config Management | Manual YAML edits or complex scripts | Automated yq mutations |