Replacing GitHub Actions deployments and environments with GitOps
If your GitHub Actions deploy job pushes Kubernetes manifests using environments, required reviewers and secrets, and that job is now under renewal, pricing or residency pressure, the deploy half can move to self-hosted Argo CD or Flux while build and test stay in CI. Both are Apache-2.0 licensed and neither project offers a paid edition of its own. This is a module swap, not a full CI replacement, so the rest of your pipeline, runners and test suite can stay where they are.
The practical change is that CI stops running kubectl apply or helm upgrade against the cluster. Instead, CI builds an image, commits the new tag to a Git repository of manifests, and the GitOps controller inside the cluster pulls and reconciles that state. Your GitHub environments and required reviewers map to pull request approvals on the manifest repository, and the cluster credentials no longer have to sit in GitHub secrets. Confirm with your platform team whether the controller will hold its own repository credentials and how those are stored, since the CI secrets that GitHub never exports still need to be re-created in the new location.
Before choosing between the two, check the parts that change most. Argo CD supports SSO through its bundled Dex or directly through an existing OIDC provider, and the user management documentation recommends disabling the built-in admin user with admin.enabled set to false once SSO is configured. Flux is driven by flux bootstrap and the Flux Operator, and it uses Kubernetes RBAC with impersonation for tenancy. Rollback also changes: in a GitOps model you revert a commit in the manifest repository rather than re-running an old GitHub Actions job, so decide which branch protections and approval rules apply to that revert. Ask your vendor or team to confirm the current Argo CD high availability requirements, including the three-node minimum for the HA manifests, before sizing the cluster.
Which GitHub Actions deployment capabilities map to GitOps tools
This table maps each deployment capability of a GitHub Actions job with environments to Argo CD, Flux, or a step that stays in CI. Read each row as a split of responsibility: what the GitOps controller takes over, what CI keeps, and where the approval or audit evidence moves. Confirm specific behavior against each project's documentation before relying on it.
| Capability | Argo CD | Flux and CI-side step |
|---|---|---|
| Environment-scoped deploy jobs | Each Application targets a cluster and namespace, and sync runs from the Git path that the environment maps to | Flux Kustomization or HelmRelease per environment path; CI no longer runs kubectl apply against the cluster |
| Required reviewers | No built-in reviewer gate on sync; approval is usually enforced by pull request review or by disabling auto-sync | No built-in reviewer gate; use branch protection and required reviews on the environment repository path |
| Environment secrets | Repository and cluster credentials are stored as Kubernetes Secrets; application secrets come from an external secret operator or sealed secrets | Secrets are referenced from Kubernetes Secrets or decrypted by the kustomize controller; confirm the decryption setup for your key manager |
| Deployment history | Sync history and revision records are kept in the Application resource; confirm retention settings for your version | Reconciliation events are visible through the Flux CLI and notification controller; Git history is the audit trail of desired state |
| Rollback | Roll back by reverting the commit or selecting an earlier revision in the UI or CLI; confirm behavior with auto-sync enabled | Revert the commit in Git and let reconciliation apply it; a tagged OCI artifact can pin a known-good state |
| Multi-cluster targets | Manages multiple clusters from one controller; each cluster must be registered and its credentials managed | Typically one Flux instance per cluster that pulls from shared Git sources; cross-cluster patterns depend on your layout |
| SSO and RBAC | SSO through bundled Dex or an existing OIDC provider, with RBAC on applications and projects; confirm the 3.0 RBAC changes | Flux relies on Kubernetes RBAC with impersonation; SSO belongs to the Git forge and cluster identity, not to Flux itself |
| Promotion and approvals | Promotion is a Git change between environment paths, often automated by CI opening pull requests | CI builds and tests the image, then commits the new tag to the environment repository; approvals sit on that pull request |
Argo CD or Flux: which deployment controller fits your team
Both controllers replace the deploy step that a GitHub Actions job runs today with a pull-based reconciler inside your cluster. The choice depends on whether your team wants a web UI and application-centric view or a set of composable controllers managed through Kubernetes APIs. Use the cards below to check fit before you commit to either one.
Argo CD: UI and application view
Argo CD runs as a Kubernetes controller with a web UI that shows each application, its sync state and its resources. It manages multiple clusters from one instance and integrates SSO over OIDC, OAuth2, LDAP and SAML 2.0 with RBAC, which maps well to environment approvals that today live in GitHub environments. It is released under Apache-2.0 with no paid edition from the project, and the CNCF moved it to Graduated on December 6, 2022. Check that the web UI and its access model match how your release managers work, and plan the RBAC and SSO setup before go-live.
Flux: composable GitOps Toolkit
Flux is built from GitOps Toolkit controllers, including the source, kustomize, helm, notification and image automation controllers, so you enable only the parts you need. It uses Kubernetes RBAC with impersonation for multi-tenancy, which suits platform teams that already manage access through Kubernetes roles. It supports Helm, Kustomize and OCI artifacts and is Apache-2.0 licensed. Confirm whether your team will accept a CLI and manifest-driven workflow instead of a web console for day-to-day promotion.
Argo CD: installation and upgrade work
Argo CD is installed as a set of workloads, and its high availability manifests need at least three nodes because of pod anti-affinity rules. Its documentation recommends disabling the built-in admin user once SSO or local users are configured, through the admin.enabled setting. Argo CD 3.0 also moved repository definitions into Kubernetes Secrets, so an upgrade from 2.14 needs config changes. Plan for the minor-release cadence (four a year, with patch releases only for the three most recent minors) as recurring work.
Flux: install paths and air-gap support
Flux installs with flux bootstrap, which is idempotent, with the Flux Terraform provider, or with the Flux Operator, which provides a declarative API for managing the controllers. Its installation documentation covers air-gapped installation, which matters if your builds run in isolated networks. Compare the install path with how your platform team already provisions clusters, and confirm that your chosen path produces the audit trail of configuration changes your change-management process requires. Check the minimum Kubernetes patch versions in the install guide before choosing a cluster version.
Both need a cluster and Git
Neither controller works without a Kubernetes cluster and a Git repository that holds the desired state. Your GitHub Actions jobs still build images and open pull requests that update manifests, but the cluster now pulls changes instead of receiving a deploy from a runner. Decide where secrets for cluster access and image pulls will live, because GitHub never exports Actions secret values and the controllers need their own credentials. Confirm which teams can merge to the configuration repository, since that merge becomes the deploy action.
Pick by team, not by feature list
Choose Argo CD when a central platform or release team wants one visual place to see every application across clusters and approve syncs. Choose Flux when platform engineers prefer Kubernetes-native RBAC, composable controllers and infrastructure-as-code install paths. Run a short evaluation on one non-production cluster, and confirm with each vendor or project which multi-tenancy and approval features your version supports before you standardize on either tool.
What stays in GitHub Actions after the deploy moves
Most of the pipeline stays where it is. Build, unit and integration tests, image signing and pushing the image to a registry usually remain in GitHub Actions, because they produce the artifact that the deployment consumes. What changes is the deploy job. Instead of running kubectl apply or helm upgrade with a cluster credential, the workflow commits a new image reference to a separate GitOps repository, and Argo CD or Flux reconciles the cluster to that state. The cluster now pulls its desired state, so GitHub Actions no longer needs a kubeconfig.
The handoff is the part to design carefully. The most reliable pattern is to pass the image digest, not the mutable tag, from the build job to the update step, so that the commit in the GitOps repository names exactly the bytes that were tested and signed. Typical implementations write the digest into a Kustomize overlay or Helm values file with a scripted commit, using a deploy key or GitHub App token with write access to that one repository only. Confirm how your chosen controller handles image updates, since Flux has an image automation controller for this, while Argo CD users commonly rely on a commit step or a separate image updater tool.
GitHub-hosted runners or your self-hosted runners still execute every CI step, and they still bill or consume capacity exactly as before. Moving the deploy half does not remove the runner cost or the need to protect runner credentials, and a compromised workflow can still push a malicious digest into the GitOps repository. Plan branch protection, required reviews on the GitOps repository and signed commits as controls on the handoff. Confirm with your platform team which runner fleet will carry the CI half, and whether the registry push credentials stay as GitHub environment secrets.
How to move deployments and environments to GitOps step by step
This sequence moves the deploy half of a GitHub Actions pipeline into a Git-driven controller, so that each environment has its own reviewed state, its own credentials and a tested rollback path before any production traffic depends on it.
Inventory environments, reviewers and secrets
Your platform or release lead lists every GitHub environment, its protection rules, required reviewers, deployment branches, and each environment secret and variable that a deploy job reads. GitHub's REST API returns secret names without values, so the values must be recovered from their original sources, such as your secrets manager or cluster, and re-created later. Done when each environment has a written owner, an approval rule and a named source for every credential.
Define Kubernetes manifests or Helm charts in Git
Your platform engineers move the rendered deployment definitions for each environment into a dedicated configuration repository, as Kubernetes manifests, Kustomize overlays or Helm charts with per-environment values files. Promotion then becomes a reviewed commit that changes an environment path, and CI keeps building and testing images. Done when a manifest change for one environment can be reviewed in a pull request and rendered locally with the same result as the current pipeline.
Install the GitOps controller
Your cluster administrators install Argo CD or Flux into a dedicated namespace using the method your platform team prefers. For Flux, the documented options are flux bootstrap, the Flux Terraform provider and the Flux Operator, and its installation guide covers air-gapped installs, so mirror the images and manifests into your registry first if the cluster has no internet access. Confirm the Kubernetes version against the minimum patch releases listed in the Flux guide before you start. Done when the controller pods are healthy and can read the configuration repository.
Recreate repository access as Kubernetes Secrets
Your platform team creates the Git repository credentials and any registry pull secrets as Kubernetes Secrets, using a deploy key or a scoped token that you issue again. Argo CD 3.0 no longer reads repositories from the argocd-cm ConfigMap, so repository definitions must be Secrets. Re-create the environment secrets from the sources recorded in step one, and never store their values in the configuration repository. Done when the controller reports each repository as connected and a test sync reads the manifests without errors.
Configure SSO and disable the admin user
Your identity team connects the controller to your existing identity provider, either through Argo CD's bundled Dex connectors or directly over OIDC, and maps groups to RBAC roles that match the reviewer lists from step one. Argo CD's user management guidance is to use the built-in admin account only for initial setup and to disable it with admin.enabled set to false. Done when a reviewer in each group can log in, can see only the applications they own, and the admin account is disabled.
Run both deployment paths in parallel
For each environment, keep the existing GitHub Actions deploy job active while the GitOps controller syncs the same release into a non-production namespace, then compare the running images, configuration and health checks. Test a rollback in the GitOps path by reverting a commit and confirming the controller restores the previous state. Done when both paths produce identical workloads in staging and the rollback has been exercised and recorded.
Cut over one environment at a time
Start with the least sensitive environment, disable the GitHub Actions deploy job for it, and make the Git commit the only route to change that environment. Repeat for each environment in order of risk, keeping the old job available until the environment has gone through a normal release. Done when every environment deploys only through reviewed commits, the old deploy jobs are removed, and your runbook names the owner of each approval and rollback step.
How approvals, promotion and rollback change
In a GitHub Actions deployment job, approvals usually sit on the environment: a job that targets an environment can wait for named reviewers before it runs. In a GitOps setup, the approval moves to the point where a change enters the cluster, which is normally a pull request into the branch or directory the controller watches. Repository administrators configure branch protection and review rules, and platform staff decide who may sync or change each application. The audit trail changes shape: approvals are recorded on the pull request and merge commit, while the sync itself is recorded by the controller.
- Environment reviewers: GitHub holds a job until named reviewers approve it and keeps the approval in the run and deployment history. Confirm which plan and repository visibility your organization uses, because environment protection options depend on them.
- Pull request approvals: Required reviews and protected branches make approval a precondition for merging into the branch the controller tracks. The evidence is the review record and the merge commit.
- Controller access: Argo CD role-based access control decides who can sync or change applications. Update and delete rights now apply to the application itself, and reading logs needs an explicit logs, get permission.
- Identity source: Approvers should sign in through SSO, and the built-in admin user should be disabled once SSO or local users are configured, as the Argo CD user management documentation recommends.
Check whether your approval rules cover every deployment path, including manual syncs and emergency changes, and whether the controller keeps enough sync history for your review cycle.
In GitHub Actions, promotion is often a workflow_dispatch run or a chained job that deploys the same build to the next environment. In a GitOps model, promotion becomes a Git change: a commit that updates the manifest, Helm values or Kustomize overlay for the next environment. The team chooses how environments are separated, by branch, by directory or by image reference, and the controller then reconciles the cluster to whatever the chosen source says. The build step should stay separate, so that the promoted artifact is the one CI produced and tested.
- Manual dispatch: An operator picks a version and a target in a
workflow_dispatchrun. Limit who can run it and which inputs are allowed. The evidence is the run record and its inputs. - Branch promotion: Each environment tracks its own branch, and promotion is a merge. Reviews are easy to follow, but branches can drift apart, so compare them on a regular schedule.
- Directory promotion: One branch holds one folder per environment, and promotion updates a version value in the next folder. Each environment gets its own reviewable diff.
- Immutable references: Promote an image digest or an immutable tag that CI produced once, not a rebuilt image. Confirm that your registry supports immutable tags before relying on them.
- Templated applications: Argo CD ApplicationSets and Flux Kustomizations can generate per-environment objects from one template. Confirm that the pattern fits your cluster count and team layout.
Check that each environment's source of truth is written down and that any promotion can be traced from artifact digest to commit to sync.
In GitHub Actions, rollback usually means re-running an earlier deployment job or dispatching a previous version, which pushes that version out through the pipeline again. In a GitOps model, rollback is a Git revert: you revert the commit that changed the desired state, and the controller reconciles the cluster back to it. Each cluster state then maps to a commit, so the rollback itself becomes part of Git history. A re-run uses the current secrets, variables and pipeline code, while a revert restores only the declared manifests.
- Re-run a job: Fast when the original run still exists, but the job executes with current variables, secrets and action versions, so the result can differ from the original deployment.
- Revert a commit: Creates a new commit that undoes the change. It goes through the same review as any other change, and the evidence is the revert commit plus the controller's sync history.
- Sync to an earlier revision: Argo CD can sync an application to a previous revision, which leaves Git and the cluster out of step until someone corrects Git. Choose a revert commit when the audit trail must match the repository.
- Stateful changes: Reverting manifests does not undo database migrations or data held outside Kubernetes. Plan those reversals separately and confirm who owns them.
- Rehearsal: Practice both paths in a non-production cluster so the operators know the steps before an incident. Record what worked and what did not.
Confirm which rollback path your change process accepts and who can execute it when Git hosting or the controller is unavailable.
Questions buyers ask before replacing GitHub Actions deployments
What does replacing GitHub Actions deployments with Argo CD or Flux cost?
The cost is mainly staff time, Kubernetes infrastructure and the work to convert deploy jobs into declarative manifests. Argo CD and Flux are both Apache-2.0 licensed, so the project itself has no license fee, and Argo CD has no paid edition from the project. The recurring costs are the clusters that run the controllers, the platform engineers who operate them, and any commercial support you choose. Costs rise with the number of clusters, environments, applications and approval rules, and fall when deployment patterns are standardized. Ask any quote to split one-time work (design, migration, pipeline changes) from recurring work (upgrades, on-call, patching), and to state which Kubernetes versions and controller releases it assumes.
How long does a GitOps migration from GitHub Actions take?
The timeline depends on how many clusters, environments and applications move, how much deploy logic lives in workflow YAML, and how approvals and secrets are handled. A pilot with one application and one non-production cluster usually comes before any production move, and the scope agreed in writing sets the milestones. No duration is fixed here because the supplied research does not give one for this kind of migration. Ask the provider for a timeline tied to a written scope, with named dependencies such as cluster access, SSO setup and secret re-creation, since those are the most common sources of delay.
Can our team migrate deployments to GitOps without outside help?
Yes, a team with Kubernetes experience and Git ownership can run the migration itself, and the Argo CD and Flux documentation covers installation, RBAC and high availability. The harder parts are the ones that need judgment: deciding how promotion between environments works, mapping GitHub environment approvals to Git-based review, and designing RBAC so that deploy rights match your change policy. Assess honestly whether anyone on the team has operated a cluster controller in production. If not, budget for training or outside help with a fixed scope, and confirm which parts you will own after handover.
What do we need to give the team before the work starts?
Expect to provide Kubernetes access with rights to install controllers in the target clusters, ownership of the Git repositories that will hold manifests, and a named owner for approvals and secrets. You will also need someone who can approve the on-call model for the controller. Argo CD runs as a Kubernetes controller with a web UI, and in high availability mode it needs at least three nodes because of pod anti-affinity rules, so confirm node capacity early. Also list every secret that CI currently holds, because GitHub's REST API returns Actions secret names without their values and those values must be re-created in the new system.
Does Argo CD or Flux need more day-to-day operation?
Both run as Kubernetes controllers that you must upgrade, monitor and secure, so neither is operation-free. Argo CD releases a minor version four times a year and only the three most recent minor versions receive patch releases, which sets a practical upgrade rhythm. Argo CD 3.0 also changed where repositories are defined, moving them into Kubernetes Secrets, so upgrades can need configuration changes. Flux is built from GitOps Toolkit controllers and is installed with flux bootstrap, the Flux Terraform provider or the Flux Operator. Compare the upgrade cadence, the number of components each tool runs, and the on-call effort in your own environment before choosing.
Does the Flux release we choose support our Kubernetes version?
Check the Flux installation guide before choosing a release, because it lists minimum supported Kubernetes patch versions: 1.34.1 or later for Kubernetes 1.34, 1.35.0 for 1.35, and 1.36.0 for 1.36 and later. The same guide advises against running end-of-life Kubernetes versions in production. If your clusters run a Kubernetes minor version below those minimums, plan a cluster upgrade before or alongside the controller work. Confirm the supported combination for your exact cluster version with the Flux documentation at release time, since the list changes as new Kubernetes versions appear.
How do SSO and approvals carry over from GitHub environments?
Argo CD supports SSO through its bundled Dex, which offers SAML, LDAP and GitHub connectors, or directly through an existing OIDC provider such as Okta, Keycloak or Microsoft. Its RBAC uses the federated_claims.user_id claim with Dex after version 3.0, and the user management documentation recommends disabling the built-in admin user with admin.enabled set to false once SSO is configured. Approvals do not map one to one: GitHub environment protection rules pause a job, while GitOps usually gates a change through a pull request review or a sync policy. Decide that design before migration, and record who can approve each environment.
What running Argo CD or Flux in production requires
Running Argo CD or Flux in production means the platform team owns a Kubernetes workload that must stay up, be patched and be kept on a supported Kubernetes version. Start with capacity: the Argo CD high availability manifests need at least three nodes because of pod anti-affinity rules, so a two-node cluster cannot run the HA layout as documented. Confirm node count, zones and the IPv6 setup of the target clusters before the design is signed off, since IPv6-only clusters are not supported.
Plan the stateful and scaling pieces separately. Argo CD keeps its state in Kubernetes objects, and Redis is a disposable cache, so losing it means a cache rebuild rather than a data restore, but the backup scope is the cluster configuration, Application objects and repository Secrets. The application controller can be sharded across replicas when many clusters or applications load it, which is a sizing decision your team makes and tests. Argo CD 3.0 requires repositories as Kubernetes Secrets, so those Secrets belong in your secret management and backup process.
Set an upgrade rhythm. Argo CD ships a minor release four times a year, and only the three most recent minor versions receive patch releases, so the team must budget for a minor upgrade roughly every three months or fall off the patch line. Flux publishes its own minimum Kubernetes patch versions, such as 1.34.1 or later for Kubernetes 1.34 and 1.36.0 or later for 1.36 and later, and its installation guide advises against running end-of-life Kubernetes in production. Check both the Argo CD and Flux compatibility notes against your Kubernetes roadmap before each cluster upgrade.
How DeployOpen scopes and delivers a GitOps deployment migration
DeployOpen plans, implements, customizes, integrates, hardens, backs up, upgrades, documents and supports self-hosted open-source platforms inside your own infrastructure. For deployments moving from GitHub Actions environments and approvals to a GitOps controller, we start with a written scope that separates what stays in CI from what the cluster controller owns.
How we scope
- Inventory every GitHub Actions deploy job, environment, required reviewer and deployment secret that reaches a Kubernetes cluster.
- Agree in writing which clusters, namespaces and promotion paths move to a GitOps controller and which stay in CI.
- Confirm the target controller, Argo CD or Flux, along with the Kubernetes versions and identity provider in use.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts. A quote follows from that written scope.
How we build
- Structure the desired-state repository, with separate paths for each environment and a defined promotion flow between them.
- Rebuild approval gates as pull request reviews or controller sync policies, and test each gate against a non-production cluster.
- Recreate deployment secrets in the target secret store, since GitHub does not return secret values through its API.
- Test rollback by reverting a commit in the desired-state repository and confirming the cluster converges to the previous state.
How we hand over
- Provide written runbooks covering sync, promotion, approval, rollback and controller upgrade procedures for your operators.
- Document the RBAC model, SSO configuration and the admin account settings used in the delivered environment.
- Walk your platform and security teams through the setup and record the evidence that supports your internal controls.
- Deliver the controls and evidence for your compliance assessment, while independent auditors and certification bodies issue any audit reports.
How we support
- Ongoing support, upgrades and continuous security testing are available as retainers after handover.
- Plan controller upgrades against each project's published release cadence and the Kubernetes versions your clusters run.
- Confirm with your vendor and the project documentation which features and patch branches apply to your chosen version before scheduling upgrades.
