***First-time GitOps Runtime installation**

***First-time GitOps Runtime installation**

If this is your first time installing a GitOps Runtime in your Codefresh account, follow these steps:

*[Complete prerequisites](#preparing-for-hybrid-gitops-runtime-installation): Before starting the installation, complete pre-requisites.

***Additional GitOps Runtimeinstallation**

***Additional GitOps Runtimeinstallations**

If you have already installed a GitOps Runtime in your account and want to install additional Runtimes on different clusters within the same account, you can continue with a[simplified installation](#install-additional-gitops-runtimes-in-account) from the Codefresh UI, or use[Terraform](/install-gitops-runtime-via-terraform).

When installing additional GitOps Runtimes, Git provider, Shared Configuration Repository, and the repository for the Helm chart, for example, are not required, as they have been already set up for your account.

%}

{:start="4"}

1. Ifthe minor appversion you have differs from that used by Codefresh, do one of the following:

1. Ifyour minor appversion differs from that used by Codefresh, do one of the following:

* Lower version: Upgrade to the required minor appversion.

* Higher version: If not available in Codefresh forks, please contact Codefresh Support.

1. In the Welcome page, select**+ Install Runtime**.

1. Select**Hybrid Runtime**.

1. Select**Hybrid Runtime**, and click**Add**.

{% include

image.html

{:start="2"}

1. If needed, select**Customize runtime values**, and define the**Runtime Name** and**Namespace**.

The default names are`codefresh` for both.

1. Copy and run the command to install the runtime Helm chart:

1. Copy and run the command to install the runtime Helm chart:

The commands differ depending on the access mode. Ingress-based or service-mesh-based access modes for the Runtime require additional flags.<br>

Unless otherwise indicated, values are automatically populated by Codefresh. If you're using a terminal, remember to copy the values from the UI beforehand.<br>

OAuth2 authorization is possible if your admin has registered an OAuth Application for Codefresh. See[OAuth2 setup for GitOps]({{site.baseurl}}/docs/administration/account-user-management/oauth-setup/).

**Git access token authorization**

Git access token authentication requires you to generate an access token in your Git provider account for the GitOps Runtime with the required scopes. For detailed information on Git Runtime token, including using tokens with custom scopes, review[GitOps Runtime token scopes]({{site.baseurl}}/docs/security/git-tokens/#git-runtime-token-scopes).

Git access token authentication requires you to generate an access token in your Git provider account for the GitOps Runtime with the required scopes. For detailed information on Git Runtime token, including using tokens with custom scopes, review[GitOps Runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#git-runtime-token-scopes).

**SSH access to Git**

By default, Git repositories use the HTTPS protocol. You can also use SSH to connect Git repositories by entering the SSH private key.

toc:true

If you have Hosted GitOps, set up your hostedruntime environment:

If you have Hosted GitOps, set up your hostedRuntime environment:

1. Provision the Hosted GitOps Runtime with a single click

1. Authorize access through your OAuth token to the organization where Codefresh creates the Git runtime repo and the shared configuration repo

1. Connect to an external K8s cluster with access to the internet, to which you can deploy applications

1. Install Argo Rollouts on the cluster

1. Provision the Hosted GitOps Runtime with a single click.

1. Authorize access through your OAuth token to the organization where Codefresh creates the Git runtime repo and the[Shared Configuration Repo]({{site.baseurl}}/docs/installation/gitops/shared-configuration/).

1. Connect to an external K8s cluster with access to the internet, to which you can deploy applications.

This is important as you cannot deploy to the in-cluster with the Hosted GitOps Runtime.

1. Install Argo Rollouts on the cluster.

Read our[blog on Hosted GitOps](https://codefresh.io/blog/codefresh-upends-continuous-delivery-with-hosted-gitops-platform-featuring-dora-dashboards-and-first-class-integrations-for-ci/).

For detailed information on each of the steps below, see[Set up a Hosted GitOps Runtime environment]({{site.baseurl}}/docs/installation/gitops/hosted-runtime/).

Verify the following:

* If you have hybrid runtimes installed, make sure you have latest version of the CLI

* Check version:

To compare with the latest version from Codefresh,[click here](https://github.com/codefresh-io/cli-v2/releases){:target="\_blank"}.

*[Download the CLI]({{site.baseurl}}/docs/installation/gitops/upgrade-gitops-cli/).

* Kubernetes cluster with access to the internet

* OAuth token

Verify that you have:

* A Kubernetes cluster with access to the internet

* An OAuth token

1. In the Codefresh UI, go to Codefresh[Home Dashboard](https://g.codefresh.io/2.0/?time=LAST_7_DAYS){:target="\_blank"}.

%}

{:start="3"}

1. Select the Git organization for the runtime installation andshared configuration repos:

1. Select the Git organization for the runtime installation andthe Shared Configuration Repo:

* Click**Connect**.

* Click**Authorize Access** and enter your OAuth token.

* Select the**Git Organization for which to create the repos**.

max-width="50%"

%}

You are now ready to create and deploy an Argo CD application.

[Create resources for codefresh-guestbook application]({{site.baseurl}}/docs/quick-start/gitops-quick-start/create-app-specs/)

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](https://github.com/codefresh-io/gitops-runtime-helm/blob/main/charts/gitops-runtime/){:target="\_blank"}. It contains all the arguments that can be configured, including optional ones.

The Runtime is installed through a Helm chart. The Codefresh`values.yaml` is located[here](https://github.com/codefresh-io/gitops-runtime-helm/blob/main/charts/gitops-runtime/){:target="\_blank"}. It contains all the arguments that can be configured, including optional ones, with descriptions of each.

Hybrid GitOps Runtimessupports 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,notrequiring an ingress controller.

Hybrid GitOps Runtimessupport 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 doesnotrequire an ingress controller.

For details on these access modes, review[GitOps Runtime architecture]({{site.baseurl}}/docs/installation/runtime-architecture/#gitops-runtime-architecture).

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]({{site.baseurl}}/docs/security/git-tokens/#git-runtime-token-scopes).

Have your GitHub Runtime tokenready for Runtime installationwith a valid expiration date and access permissions:

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`

**Before you begin**

* Make sure your cluster does not have[Argo project components & CRDs](#argo-project-components--crds)

**How to**

1. In the Welcome page, select**+ Install Runtime**.

1. From Runtimes in the sidebar, select**GitOps Runtimes**.

1. Click**Hybrid Runtimes**, and then click**Add**.

1. Set up your Git provider account:

1. If not GitHub, select the Git provider.

1. Define the provider's API URL.

1. Install the Hybrid GitOps Runtime:

1. Click**Generate** to create a new API key.

1. Retain the default values for the GitOps Runtime name and namespace,`codefresh`.

1. Copy the command in_Step 3_ and run it to add the repository in which to store the Helm chart. You don't need to change anything in the command.

1. Copy the command in_Step 4_ and run it to install the Helm chart for the Hybrid GitOps Runtime:

1. 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 theruntime.

*`<cf-gitops-runtime/gitops-runtime>` is the name of the repo and must be identical to the one specified in_Step 3_, and is by default,`cf-gitops-runtime`.`gitops-runtime` is the name of the Helm chart predefined by Codefresh, and cannot be changed.

*`codefresh` is the default name of theRuntime.

*`oci://quay.io/codefresh/gitops-runtime` is the name of the Helm chart, predefined by Codefresh, and cannot be changed.

{% include

image.html

lightbox="true"

file="/images/quick-start/gitops/install-helm-command.png"

url="/images/quick-start/gitops/install-helm-command.png"

file="/images/runtime/helm/helm-install-hybrid-runtime.png"

url="/images/runtime/helm/helm-install-hybrid-runtime.png"

alt="Quick Start: Install Hybrid GitOps Runtime"

caption="Quick Start: Install Hybrid GitOps Runtime"

max-width="60%"

%}

{:start="5"}

1. Wait for a few minutes, and then click**Close**.

{:start="6"}

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.

1. Optional. Complete the installation by clicking**Configure as Argo Application**.

There is no need for any 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.

1. 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.

If this is your first time installing GitOps in Codefresh, review and confirm that your deployment environment conforms to the minimum requirements for Hybrid GitOps installation. Check the[system requirements]({{site.baseurl}}/docs/installation/gitops/hybrid-gitops/#minimum-system-requirements).

If this is your first time installing GitOps in Codefresh, review and confirm that your deployment environment conforms to the minimum requirements for Hybrid GitOps installation. Check the[system requirements]({{site.baseurl}}/docs/installation/gitops/hybrid-gitops-helm-installation/#minimum-system-requirements).

If you already have a CLI-based Hybrid GitOps Runtime installed on your cluster, you have two options:

1. To install on the same cluster, first uninstall the existing CLI-based Hybrid GitOps Runtime.

This is the recommended option.

1. Install on a different cluster, verifying that you meet the minimum requirements.

If you already have a CLI-based Hybrid GitOps Runtime installed on your cluster, you_must migrate your CLI-based Runtime to the Helm-based Runtime_.

Read and follow the guidelines in[Migrating GitOps Runtimes from CLI to Helm]({{site.baseurl}}/docs/installation/gitops/migrate-cli-runtimes-helm/).

* Before you run uninstall an existing CLI-based Hybrid GitOps Runtime from the Codefresh UI, or run`cf runtime <name> uninstall` from the CLI,_delete_ all Codefresh-related namespaces.

* If a namespace is frozen in the`Terminating` status, it could be because the namespace has resources with`finalizers` that are preventing deletion.

Here's how you can remove`finalizers` using`k9s`:

* In the`applications` view, do the following for each application:

* Hit`e` to edit the YAML.

* Scroll down to the section entitled`finalizers`.

* Move cursor to the line with the finalizer definition, and then hit`dd` to delete the line.

* Delete also the`finalizers` key.

* To save and exit, hit`escape``wq:``enter`.

* Try deleting the namespace again.

[Install a Hybrid GitOps Runtime]({{site.baseurl}}/docs/quick-start/gitops-quick-start/runtime/)