> ## Documentation Index
> Fetch the complete documentation index at: https://mogenius-docs-self-hosted-helm-values-update.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# GitOps
GitOps (short for Git Operations) describes a declarative way of managing applications in cloud-native environments using the Git workflow. This means, application configurations are stored and updated via Git repositories. To track and synchronize the Git repositories with Kubernetes, a GitOps engine is used on the clusters.
mogenius comes with a native GitOps integration that allows you to easily implement GitOps in your teams, or to integrate the mogenius platform with your existing GitOps stack. This way, you can easily deploy workloads and resources to Kubernetes using the UI with mogenius Workspaces (see [Deploying Applications](https://docs.mogenius.com/deploying-applications)). Then, you can add GitOps as a layer of stability and control.
**Here's how you can use that in your teams:**
* Deploy containers to Kubernetes using the mogenius UI, without requiring deep Kubernetes knowledge. Then, add them to GitOps for deploying them to production-grade deployments.
* Configure your applications once and then deploy them to additional environments for a staged development workflow. See [Multi-Environment Deployments](/deploying-applications/multi-environment-deployments) for a practical guide.
* Backup all your manifests to recover your cluster state in case of an incident.
## How the GitOps workflow works in mogenius
The GitOps workflow in mogenius follows a UI-first approach. You don't need to write Kubernetes manifests manually — mogenius generates them for you.
Here's the end-to-end flow:
1. **Deploy via the UI**: Use the mogenius UI to deploy applications through [container images](/deploying-applications/container-images), [pipeline starters](/deploying-applications/pipeline-starters), [Helm charts](/deploying-applications/helm-charts), or [Kubernetes manifests](/deploying-applications/kubernetes-manifests).
2. **Enable GitOps** on your cluster (see setup below).
3. **Create a GitOps application** that includes your deployments.
4. **Manifests are auto-generated**: mogenius automatically creates the Kubernetes manifests (`application.yaml`) for all selected resources and commits them to your Git repository. You do not need to write these manifests yourself.
5. **Changes sync through Git**: When you modify configurations in the mogenius UI (environment variables, health checks, scaling, etc.), the changes are committed to Git. ArgoCD then syncs the updated manifests to your cluster.
This means you get the speed and simplicity of UI-based deployments combined with the reliability and auditability of Git-based infrastructure management.
## GitOps setup
You can configure GitOps for each cluster. Navigate to **Clusters** in your organization and open the tab **GitOps**. Click the button to enable GitOps and open the configuration page.
mogenius comes with a pre-configured stack for enabling GitOps consisting of two main applications:
1. ArgoCD: mogenius relies on the open-source project [ArgoCD](https://github.com/argoproj/argo-cd) as the GitOps engine.
2. Sealed Secrets: To securely synchronize secrets with Git, mogenius uses [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to encrypt secrets when transferring them to Git.
The setup form uses defaults that should work out of the box. You can overwrite them to customize the installation.
Already have ArgoCD and/or Sealed Secrets installed on your cluster? If possible, mogenius detects existing installations and updates the settings in the setup form. Check the default values and adjust them if they don't match your installation.
Your applications on a cluster will be synced with a Git repository. mogenius supports both GitHub and GitLab as providers.
To set up a GitHub repository, go to github.com and perform the following steps:
* Create a new repository and make sure it has a branch.
* Create a Personal Access Token. It requires at least `read/write` permissions on `Contents`. This way mogenius can commit changes on applications to the repository. If you want to use pull requests instead, make sure that the access token has `read/write` permissions for `Pull Requests` as well. Make sure to copy the PAT to a safe location.
**Branch protection and direct commits:** If you enable branch protection rules on your repository (e.g., requiring pull request reviews), direct commits from the mogenius UI will fail with an error. In this case, you must use the pull request workflow instead. The mogenius UI provides buttons to create pull requests when saving changes to GitOps-managed resources.
To set up a GitLab repository, go to gitlab.com (or your self-hosted GitLab instance) and perform the following steps:
* Create a new repository (project) and make sure it has a branch.
* Create a Personal Access Token. Navigate to **User Settings** → **Access Tokens** and create a new token.
GitLab's fine-grained personal access tokens are currently in Beta. For reliable integration, use a **Personal Access Token (classic)** instead.
The token requires the following scopes:
* `read_user` — Read access to your user profile
* `read_repository` — Read access to the repository
* `write_repository` — Write access to the repository
* `read_api` — Read access to the API
* `api` — Full API access (required for write operations)
Make sure to copy the token to a safe location before leaving the page.
**Branch protection and direct commits:** If you enable branch protection rules on your repository (e.g., requiring merge request approvals), direct commits from the mogenius UI will fail with an error. In this case, you must use the pull request workflow instead. The mogenius UI provides buttons to create merge requests when saving changes to GitOps-managed resources.
You can use the same repository for multiple clusters. Your applications will be managed using the following structure for folders and files:\
`your-repository/mogenius/CLUSTER/APPLICATION/application.yaml`
Now, in your GitOps settings in mogenius, click **Connect repository** and follow the steps:
* Enter a name for the repository.
* Enter the Personal Access Token.
* Your username and a dropdown to select your repository will load. In the dropdown, search for your GitOps repository and select it.
* Set the commit behavior: By default, mogenius will commit changes directly on the branch of your application. Activate the toggle to create pull requests instead.
* Save your settings to connect the repository.
You can proceed with creating applications.
## Applications
Your workloads and resources in Kubernetes are tracked in GitOps as applications. Each application consists of one or more resources.
Typical examples for how applications can be defined:
* A deployment for your container, plus Ingress, Service, and Secrets that are used by the deployment.
* A platform deployment consisting of several microservices.
You can create applications in your cluster settings as an admin, or within Workspaces. In your cluster, scroll to the bottom of your **GitOps** page. In a Workspace, navigate to the page **GitOps applications**. Click the button **Create application** to configure a new application.
Here's how it works:
* Enter a name for your application. This is how it will be displayed in mogenius and it will be added as a folder to your Git repository.
* From the list of namespaces on your cluster, select the resources that you want to include in your application. You can select one namespace per application. Inside a namespace you can select all resources, or a selected list of resources.
* Confirm to create your application.
Your application is now added to the list, and mogenius automatically generates the Kubernetes manifests for all selected resources and stores them as `application.yaml` in your Git repository. It can take a few minutes until ArgoCD has synchronized it, and you'll see a loading animation in the meantime. Once it is synced, you'll see the status of your application and all included resources.
## Working with GitOps in mogenius
When workloads or resources in your Workspaces are part of an application (i.e. managed via GitOps), a status object `Application` will be shown. This indicates the sync status of the directory and the application. If an error occurs, you can hover over the status to view the error message.
### Updating workloads
You can continue using the mogenius UI to change configurations such as environment variables, resource limits, health checks, or YAML manifests on any resource. When saving changes, mogenius detects that GitOps is enabled for the resource and will update the corresponding `application.yaml` in Git. This follows the commit behavior defined in your cluster settings (direct commit or pull request). Changes are not applied directly to the cluster but will be synced by ArgoCD within a few minutes. You can monitor this sync using the Application status.
### GitOps log
You can track the history and changes of your `application.yaml` using the **GitOps log**. It is available on any resource managed by a GitOps application and shows commits and pull requests.
## ApplicationSets
ApplicationSets allow you to deploy applications from an external Git repository directly to your cluster using ArgoCD. Unlike standard Applications (which track mogenius-managed resources), ApplicationSets sync manifests that already exist in a Git repository — ideal for teams with existing Kubernetes configurations, Helm charts, or Kustomize overlays.
**When to use ApplicationSets:**
* You have existing Kubernetes manifests, Helm charts, or Kustomize overlays in Git
* You want to deploy the same application to multiple environments from a single source
* You're integrating mogenius with an existing GitOps workflow
### Creating an ApplicationSet
Navigate to **Clusters → \[Your Cluster] → GitOps** and click **Create ApplicationSet**.
* **ApplicationSet name**: A unique name for this ApplicationSet
* **Repository**: Select a connected Git repository containing your manifests
* **Branch**: The branch to sync from
* **Path**: The directory containing your manifests (e.g., `apps/my-service/overlays/prod`)
Choose how ArgoCD should interpret the contents of the path:
| Source Type | Use When | Path Must Contain |
| ------------- | ------------------------------- | ------------------------ |
| **Directory** | Plain Kubernetes YAML manifests | `.yaml` or `.json` files |
| **Helm** | Helm chart | `Chart.yaml` |
| **Kustomize** | Kustomize overlay | `kustomization.yaml` |
Depending on your source type, additional options are available:
**For Helm sources:**
* **Values Files**: Paths to values files (one per line, relative to chart directory). Files are applied in order — later files override earlier ones.
**For Kustomize sources:** See [Kustomize configuration](#kustomize-configuration) below.
Specify where ArgoCD should deploy resources if the manifests don't include a namespace. Leave empty to use the ArgoCD default namespace.
Once created, the ApplicationSet appears in your GitOps overview. ArgoCD will sync the manifests from Git and deploy them to your cluster. The sync status shows whether the cluster state matches the Git repository.
### Kustomize configuration
When using Kustomize as the source type, you can configure additional transformations that ArgoCD applies during deployment:
| Option | Description | Example |
| ----------------------- | ------------------------------------------------ | ------------------------------ |
| **Kustomize Namespace** | Override the namespace in all manifests | `production` |
| **Name Prefix** | Prepend a string to all resource names | `prod-` |
| **Name Suffix** | Append a string to all resource names | `-v2` |
| **Image Overrides** | Replace container images (one per line) | `nginx=my-registry/nginx:1.21` |
| **Common Labels** | Add labels to all resources (key=value per line) | `env=production` |
| **Common Annotations** | Add annotations to all resources | `owner=platform-team` |
If both **Target Namespace** and **Kustomize Namespace** are set but differ, Kustomize Namespace takes precedence and overrides the namespace in your manifests before deployment.
**Example: Deploying to production with Kustomize**
For a production deployment with environment-specific settings:
* **Path**: `apps/my-service/overlays/prod`
* **Kustomize Namespace**: `production`
* **Name Prefix**: `prod-`
* **Image Overrides**: `my-app=ghcr.io/myorg/my-app:v2.1.0`
* **Common Labels**: `app.kubernetes.io/env=production`
### Managing ApplicationSets
ApplicationSets are listed alongside standard Applications in the GitOps overview. You can:
* View the sync status and included resources
* Delete an ApplicationSet (this removes the ArgoCD ApplicationSet but does not delete deployed resources by default)
To update an ApplicationSet's configuration, delete it and create a new one with the updated settings.
## Argo CD Projects
Argo CD Projects provide a way to organize applications and control access to cluster resources. When connecting a Git repository, you can assign it to a specific Argo CD Project.
By default, mogenius creates a `mogenius` project for your applications. If you have existing Argo CD Projects on your cluster, you can select them when configuring a repository:
1. Navigate to **Clusters → \[Your Cluster] → GitOps**
2. When adding or editing a repository connection, use the **ArgoCD Project** dropdown to select the target project
Projects are useful for:
* Separating applications by team or environment
* Applying different sync policies or access controls
* Integrating with existing Argo CD setups that use project-based organization
## CI/CD integration with GitHub Actions
For teams that want to combine CI/CD builds with GitOps-based deployment, mogenius provides GitHub Actions workflow templates in the [mogenius build-workflows repository](https://github.com/mogenius/build-workflows). These templates automate the process of building your container image and triggering the mogenius operator to update the deployment, which is then tracked and synced by GitOps.
You can use these templates in two ways:
* **Through Pipeline Starters**: The easiest approach — mogenius sets up the GitHub Actions workflow for you directly from the UI. See [Pipeline Starters](/deploying-applications/pipeline-starters) for details.
* **Custom integration**: Use the workflow templates directly in your own CI/CD pipelines for more control over the build and deployment process.
## Working with Sealed Secrets
When GitOps is enabled, secrets cannot be stored in Git as plain text — they would be exposed to anyone with repository access. mogenius uses [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to solve this: secrets are encrypted before being committed to Git, and only the Sealed Secrets controller running on your cluster can decrypt them.
### How secrets flow through GitOps
When you create a Secret through the mogenius UI with GitOps enabled:
1. **You create a Secret** using the [Secrets & Configs](/deploying-applications/deployment-configuration#secrets-and-configmaps) page in your workspace
2. **mogenius encrypts it** using the Sealed Secrets controller's public certificate
3. **A SealedSecret is committed** to your Git repository (encrypted, safe to store in Git)
4. **ArgoCD syncs** the SealedSecret to your cluster
5. **The controller decrypts it** and creates a regular Kubernetes Secret that your pods can use
This happens automatically — you work with secrets normally in the UI, and mogenius handles the sealing and Git commits.
### Creating secrets
To create a secret that will be managed through GitOps:
1. Navigate to your workspace and open the **Secrets & Configs** page
2. Click **Create Secret** and enter your key-value pairs
3. Save the secret — mogenius creates the Secret in your cluster
4. Add the secret to a GitOps application to include it in Git sync
Once the secret is part of a GitOps application, mogenius automatically seals it and commits the SealedSecret to your repository. The encrypted secret in Git is safe to store — only the Sealed Secrets controller on your cluster can decrypt it.
### Viewing secrets
**In the mogenius UI:**
The Secrets & Configs page shows all secrets in your workspace. You can view the keys (but not values) and see which deployments reference each secret.
**Using mocli:**
Use the [mogenius CLI](/workspaces/mogenius-CLI) to view secrets from your terminal:
```bash theme={null}
# List secrets in a namespace
mocli get secrets -n
# View a secret's data (base64 encoded)
mocli get secret -n -o yaml
```
You can also browse secrets interactively in the mocli TUI — launch `mocli`, navigate to your namespace, and type `:secrets` to switch to the secrets view.
**What's in Git:**
The SealedSecret in your repository contains encrypted data that is not human-readable. This is expected — it ensures secrets are safe even if your repository is compromised.