Improve this page on GitHub

Install Hybrid GitOps Runtime

Install the Helm-based Hybrid GitOps Runtime

Get up and running with Codefresh by installing the Hybrid Runtime for GitOps via Helm. The Runtime is installed through a Helm chart. The Codefresh values.yaml is located here. It contains all the arguments that can be configured, including optional ones, with descriptions of each.

Quick start assumptions

The quick start assumes that you are installing the first Hybrid GitOps Runtime in your Codefresh account.

Argo project components & CRDs

Hybrid GitOps installation requires a cluster without Argo project components and CRDs (Custom Resource Definitions).

Argo project components include Argo Rollouts, Argo CD, Argo Events, and Argo Workflows.

You can handle Argo project CRDs outside the chart, or as recommended, adopt the CRDs to be managed by the GitOps Runtime Helm release.

If you already have Argo project CRDs on your cluster, do one of the following:

  • Handle Argo projects CRDs outside of the chart (see Argo’s readme on Helm charts)
    Disable CRD installation under the relevant section for each of the Argo projects in the Helm chart:
    --set <argo-project>.crds.install=false
    where:
    <argo-project> is the argo project component: argo-cd, argo-workflows, argo-rollouts and argo-events.

  • Adopt the CRDs
    Adopting the CRDs allows them to be managed by the gitops-runtime helm release. Doing so ensures when you upgrade the Hybrid GitOps Runtime, the CRDs are also automatically upgraded.

    Run this script before installation:

#!/bin/sh
RELEASE=<helm-release-name>
NAMESPACE=<target-namespace>
kubectl label --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) app.kubernetes.io/managed-by=Helm
kubectl annotate --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) meta.helm.sh/release-name=$RELEASE
kubectl annotate --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) meta.helm.sh/release-namespace=$NAMESPACE

Tunnel-based Runtime

Hybrid GitOps Runtimes support tunnel-based, ingress-based, and service-mesh-based access modes.
For the quick start, we’ll use the tunnel-based mode which is the default access mode that does not require an ingress controller.
For details on these access modes, review GitOps Runtime architecture.

GitHub as Git provider

Hybrid GitOps Runtimes require a Git Runtime token for authentication to the Git installation repository based on your Git provider, and a Git user token to authenticate Git-based actions for the Runtime.
The quick start uses GitHub as the Git provider. For other Git providers and token requirements, see Git providers and Git runtime tokens.

Have your GitHub Runtime token with a valid expiration date and access permissions ready for Runtime installation:

  • Expiration: Either the default of 30 days or any duration you consider logical.
  • Access scopes: Set to repo and admin-repo.hook

GitHub PAT permissions

GitHub PAT permissions

If you need detailed information on GitHub tokens, see the GitHub article.

Shared Configuration Repository

When you select the Git provider, Codefresh prompts you to also select the Shared Configuration Repository for your account. The repo stores account-level configuration settings and manifests. Because the Shared Configuration Repo is defined at the account-level, the Git provider you select for the first Runtime in your account is used for all the other Runtimes in the same account. Read up on the Shared Configuration Repository.

Install Hybrid GitOps Runtime

Before you begin
How to
  1. In the Welcome page, select + Install Runtime.
  2. From Runtimes in the sidebar, select GitOps Runtimes.
  3. Click Hybrid Runtimes, and then click Add.
  4. Set up your Git provider account:
    1. If not GitHub, select the Git provider.
    2. Define the provider’s API URL.
    3. Define the URL of the Shared Configuration Repository.
    4. Click Next.
  5. Install the Hybrid GitOps Runtime:
    1. Click Generate to create a new API key.
    2. Retain the default values for the GitOps Runtime name and namespace, codefresh.
    3. Copy the command in Step 3 and run it to install the Helm chart for the Hybrid GitOps Runtime:
      where:
      • cf-gitops-runtime is the default name of the Helm release, which you can change if needed.
      • codefresh is the default namespace in which to install the Hybrid GitOps runtime.
      • <codefresh-account-id> is mandatory for tunnel-based Hybrid GitOps Runtimes, and is automatically populated by Codefresh in the command.
      • <codefresh-token> is the API key you generated, and is automatically populated in the command.
      • codefresh is the default name of the Runtime.
      • oci://quay.io/codefresh/gitops-runtime is the name of the Helm chart, predefined by Codefresh, and cannot be changed.

Quick Start: Install Hybrid GitOps Runtime

Quick Start: Install Hybrid GitOps Runtime
  1. Wait for a few minutes, and then click Close.
    You are taken to the List View for GitOps Runtimes where you can see the Hybrid GitOps Runtime you added with a green dot indicating that it is online, and the Type column for the Runtime displaying Helm.
  2. Complete the installation by clicking Configure as Argo Application.
    There is no need for any further action from you, as Codefresh takes care of the configuration. By configuring the Hybrid GitOps Runtime as an Argo Application, you can ensure that GitOps is the single source of truth for the Runtime, and view and monitor Runtime components.

You are now ready to create and deploy a GitOps application in Codefresh.

What to do next

Create resources for codefresh-guestbook application