diff --git a/_docs/reference/git-tokens.md b/_docs/reference/git-tokens.md index a8e28e3d..47b7ae88 100644 --- a/_docs/reference/git-tokens.md +++ b/_docs/reference/git-tokens.md @@ -53,7 +53,7 @@ The Git runtime token is mandatory for runtime installation.
{:/} -#### Bitbucket Cloud & Bitbucket Server runtime token scopes +#### Bitbucket Server runtime token scopes * `Project admin` * `Repository write` @@ -73,7 +73,7 @@ The Git personal token is a user-specific personal access token per provisioned
{:/} -#### GitHub & GitHub Enterprise personal user token scopes +#### GitHub and GitHub Enterprise personal user token scopes * `repo` + + #### Ingress controller flags + **Skip ingress** Required, if you are using an unsupported ingress controller. For unsupported ingress controllers, bypass installing ingress resources with the `--skip-ingress` flag. @@ -102,46 +138,239 @@ For both CLI wizard and Silent install: * For existing installations, commit changes to the installation repository by modifying the `app-proxy ingress` and `.yaml` See [(Optional) Internal ingress host configuration for existing hybrid runtimes](#optional-internal-ingress-host-configuration-for-existing-hybrid-runtimes). +{::nomarkdown} +
+{:/} + + + +#### Git provider and repo flags +The Git provider defined for the runtime. + +>Because Codefresh creates a [shared configuration repo]({{site.baseurl}}/docs/reference/shared-configuration) for the runtimes in your account, the Git provider defined for the first runtime you install in your account is used for all the other runtimes in the same account. + +You can define any of the following Git providers: +* GitHub: + * [GitHub](#github) (the default Git provider) + * [GitHub Enterprise](#github-enterprise) +* GitLab: + * [GitLab Cloud](#gitlab-cloud) + * [GitLab Server](#gitlab-server) +* Bitbucket: + + * [Bitbucket Server](#bitbucket-server) {::nomarkdown}
{:/} -#### Git repository flags -**Repository URLs** -The GitHub repository to house the installation definitions. -* CLI wizard: If the repo doesn't exist, Codefresh creates it during runtime installation. -* Silent install: Required. Add the `--repo` flag. +##### GitHub +GitHub is the default Git provider for hybrid runtimes. Being the default provider, for both the CLI wizard and Silent install, you need to provide only the repository URL and the Git runtime token. -**Git runtime token** -Required. -The Git token authenticating access to the GitHub installation repository. -* Silent install: Add the `--git-token` flag. +> For the required scopes, see [GitHub and GitHub Enterprise runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#github-and-github-enterprise-runtime-token-scopes). + +`--repo --git-token ` + +where: +* `--repo ` (required), is the `HTTPS` clone URL of the Git repository for the runtime installation, including the `.git` suffix. Copy the clone URL from your GitHub website (see [Cloning with HTTPS URLs](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories#cloning-with-https-urls){:target="\_blank"}). + If the repo doesn't exist, copy an existing clone URL and change the name of the repo. Codefresh creates the repository during runtime installation. + + Repo URL format: + `https://github.com//reponame>.git[/subdirectory][?ref=branch]` + where: + * `/` is your username or organization name, followed by the name of the repo, identical to the HTTPS clone URL. For example, `https://github.com/nr-codefresh/codefresh.io.git`. + * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the runtime is installed in the root of the repository. For example, `/runtimes/defs`. + * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the runtime is installed in the default branch. For example, `codefresh-prod`. + + Example: + `https://github.com/nr-codefresh/codefresh.io.git/runtimes/defs?ref=codefresh-prod` +* `--git-token ` (required), is the Git token authenticating access to the runtime installation repository (see [GitHub runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#github-and-github-enterprise-runtime-token-scopes)). + +{::nomarkdown} +
+{:/} + +##### GitHub Enterprise + +> For the required scopes, see [GitHub and GitHub Enterprise runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#github-and-github-enterprise-runtime-token-scopes). + + +`--enable-git-providers --provider github --repo --git-token ` + +where: +* `--enable-git-providers` (required), indicates that you are not using the default Git provider for the runtime. +* `--provider github` (required), defines GitHub Enterprise as the Git provider for the runtime and the account. +* `--repo ` (required), is the `HTTPS` clone URL of the Git repository for the runtime installation, including the `.git` suffix. Copy the clone URL for HTTPS from your GitHub Enterprise website (see [Cloning with HTTPS URLs](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories#cloning-with-https-urls){:target="\_blank"}). + If the repo doesn't exist, copy an existing clone URL and change the name of the repo. Codefresh creates the repository during runtime installation. + Repo URL format: + + `https://ghe-trial.devops.cf-cd.com//.git[/subdirectory][?ref=branch]` + where: + * `/` is your username or organization name, followed by the name of the repo. For example, `codefresh-io/codefresh.io.git`. + * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the runtime is installed in the root of the repository. For example, `/runtimes/defs`. + * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the runtime is installed in the default branch. For example, `codefresh-prod`. + + Example: + `https://ghe-trial.devops.cf-cd.com/codefresh-io/codefresh.io.git/runtimes/defs?ref=codefresh-prod` +* `--git-token ` (required), is the Git token authenticating access to the runtime installation repository (see [GitHub runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#github-and-github-enterprise-runtime-token-scopes)). {::nomarkdown}
{:/} +##### GitLab Cloud +> For the required scopes, see [GitLab Cloud and GitLab Server runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#gitlab-cloud-and-gitlab-server-runtime-token-scopes). + + +`--enable-git-providers --provider gitlab --repo --git-token ` + +where: +* `--enable-git-providers`(required), indicates that you are not using the default Git provider for the runtime. +* `--provider gitlab` (required), defines GitLab Cloud as the Git provider for the runtime and the account. +* `--repo ` (required), is the `HTTPS` clone URL of the Git project for the runtime installation, including the `.git` suffix. Copy the clone URL for HTTPS from your GitLab website. + If the repo doesn't exist, copy an existing clone URL and change the name of the repo. Codefresh creates the repository during runtime installation. + + > Important: You must create the group with access to the project prior to the installation. + + Repo URL format: + + `https://gitlab.com//.git[/subdirectory][?ref=branch]` + where: + * `` is either your username, or if your project is within a group, the front-slash separated path to the project. For example, `nr-codefresh` (owner), or `parent-group/child-group` (group hierarchy) + * `` is the name of the project. For example, `codefresh`. + * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the runtime is installed in the root of the repository. For example, `/runtimes/defs`. + * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the runtime is installed in the default branch. For example, `codefresh-prod`. + + Examples: + `https://gitlab.com/nr-codefresh/codefresh.git/runtimes/defs?ref=codefresh-prod` (owner) + + `https://gitlab.com/parent-group/child-group/codefresh.git/runtimes/defs?ref=codefresh-prod` (group hierarchy) + +* `--git-token ` (required), is the Git token authenticating access to the runtime installation repository (see [GitLab runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#gitlab-cloud-and-gitlab-server-runtime-token-scopes)). + + +{::nomarkdown} +
+{:/} + + + +##### GitLab Server + +> For the required scopes, see [GitLab Cloud and GitLab Server runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#gitlab-cloud-and-gitlab-server-runtime-token-scopes). + +`--enable-git-providers --provider gitlab --repo --git-token ` + +where: +* `--enable-git-providers` (required), indicates that you are not using the default Git provider for the runtime. +* `--provider gitlab` (required), defines GitLab Server as the Git provider for the runtime and the account. +* `--repo ` (required), is the `HTTPS` clone URL of the Git repository for the runtime installation, including the `.git` suffix. + If the project doesn't exist, copy an existing clone URL and change the name of the project. Codefresh creates the project during runtime installation. + + > Important: You must create the group with access to the project prior to the installation. + + Repo URL format: + `https://gitlab-onprem.devops.cf-cd.com//.git[/subdirectory][?ref=branch]` + where: + * `` is your username, or if the project is within a group or groups, the name of the group. For example, `nr-codefresh` (owner), or `parent-group/child-group` (group hierarchy) + * `` is the name of the project. For example, `codefresh`. + * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the runtime is installed in the root of the repository. For example, `/runtimes/defs`. + * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the runtime is installed in the default branch. For example, `codefresh-prod`. + + Examples: + `https://gitlab-onprem.devops.cf-cd.com/nr-codefresh/codefresh.git/runtimes/defs?ref=codefresh-prod` (owner) + + `https://gitlab-onprem.devops.cf-cd.com/parent-group/child-group/codefresh.git/runtimes/defs?ref=codefresh-prod` (group hierarchy) + +* `--git-token ` (required), is the Git token authenticating access to the runtime installation repository (see [GitLab runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#gitlab-cloud-and-gitlab-server-runtime-token-scopes)). + + +{::nomarkdown} +
+{:/} + + + +##### Bitbucket Server + +> For the required scopes, see [Bitbucket Server runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#bitbucket-server-runtime-token-scopes). + + +`--enable-git-providers --provider bitbucket-server --repo --git-user --git-token ` + +where: +* `--enable-git-providers` (required), indicates that you are not using the default Git provider for the runtime. +* `--provider gitlab` (required), defines Bitbucket Cloud as the Git provider for the runtime and the account. +* `--repo ` (required), is the `HTTPS` clone URL of the Git repository for the runtime installation, including the `.git` suffix. + If the project doesn't exist, copy an existing clone URL and change the name of the project. Codefresh then creates the project during runtime installation. + >Important: Remove the username, including @ from the copied URL. + + Repo URL format: + + `https://bitbucket-server-8.2.devops.cf-cd.com:7990/scm//.git[/subdirectory][?ref=branch]` + where: + * `` is your username or organization name. For example, `codefresh-io.`. + * `` is the name of the repo. For example, `codefresh`. + * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the runtime is installed in the root of the repository. For example, `/runtimes/defs`. + * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the runtime is installed in the default branch. For example, `codefresh-prod`. + + Example: + `https://bitbucket-server-8.2.devops.cf-cd.com:7990/scm/codefresh-io/codefresh.git/runtimes/defs?ref=codefresh-prod` +* `--git-user ` (required), is your username for the Bitbucket Server account. +* `--git-token ` (required), is the Git token authenticating access to the runtime installation repository (see [Bitbucket runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#bitbucket-server-runtime-token-scopes)). + +{::nomarkdown} +

+{:/} + #### Codefresh resource flags **Codefresh demo resources** Optional. Install demo pipelines to use as a starting point to create your own pipelines. We recommend installing the demo resources as these are used in our quick start tutorials. -* Silent install: Add the `--demo-resources` flag. By default, set to `true`. +* Silent install: Add the `--demo-resources` flag, and define its value as `true` (default), or `false`. For example, `--demo-resources=true` **Insecure flag** For _on-premises installations_, if the Ingress controller does not have a valid SSL certificate, to continue with the installation, add the `--insecure` flag to the installation command. {::nomarkdown} -
-{:/} -{::nomarkdown} -
+

{:/} + ### Install the Codefresh CLI Install the Codefresh CLI using the option that best suits you: `curl`, `brew`, or standard download. @@ -151,10 +380,11 @@ If you are not sure which OS to select for `curl`, simply select one, and Codefr

{:/} -### Install the hybrid runtime +### Install the hybrid runtime **Before you begin** * Make sure you meet the [minimum requirements]({{site.baseurl}}/docs/runtime/requirements/#minimum-requirements) for runtime installation +* Make sure you have [runtime token with the required scopes from your Git provdier]({{site.baseurl}}/docs/reference/git-tokens) * [Download or upgrade to the latest version of the CLI]({{site.baseurl}}/docs/clients/csdp-cli/#upgrade-codefresh-cli) * Review [Hybrid runtime installation flags](#hybrid-runtime-installation-flags) * Make sure your ingress controller is configured correctly: @@ -196,15 +426,13 @@ If you are not sure which OS to select for `curl`, simply select one, and Codefr ### Hybrid runtime components -**Git repositories** - +**Git repositories** * Runtime install repository: The installation repo contains three folders: apps, bootstrap and projects, to manage the runtime itself with Argo CD. * Git source repository: Created with the name `[repo_name]_git-source`. This repo stores manifests for pipelines with sources, events, workflow templates. See [Add Git Sources to runtimes]({{site.baseurl}}/docs/runtime/git-sources/). * Shared configuration repository: Stores configuration and resource manifests that can be shared across runtimes, such as integration resources. See [Shared configuration repository]({{site.baseurl}}/docs/reference/shared-configuration/) **Argo CD components** - * Project, comprising an Argo CD AppProject and an ApplicationSet * Installations of the following applications in the project: * Argo CD @@ -213,7 +441,6 @@ If you are not sure which OS to select for `curl`, simply select one, and Codefr * Argo Rollouts **Codefresh-specific components** - * Codefresh Applications in the Argo CD AppProject: * App-proxy facilitating behind-firewall access to Git * Git Source entity that references the`[repo_name]_git-source` @@ -224,8 +451,8 @@ Once the hybrid runtime is successfully installed, it is provisioned on the Kube
{:/} -### (Optional) Internal ingress host configuration for existing hybrid runtimes +### (Optional) Internal ingress host configuration for existing hybrid runtimes If you already have provisioned hybrid runtimes, to use an internal ingress host for app-proxy communication and an external ingress host to handle webhooks, change the specs for the `Ingress` and `Runtime` resources in the runtime installation repository. Use the examples as guidelines. `/apps/app-proxy/overlays//ingress.yaml`: change `host` @@ -302,4 +529,4 @@ data: [Add external clusters to runtimes]({{site.baseurl}}/docs/runtime/managed-cluster/) [Manage provisioned runtimes]({{site.baseurl}}/docs/runtime/monitor-manage-runtimes/) [Monitor provisioned hybrid runtimes]({{site.baseurl}}/docs/runtime/monitoring-troubleshooting/) -[Troubleshoot hybrid runtime installation]({{site.baseurl}}/docs/troubleshooting/runtime-issues/) +[Troubleshoot hybrid runtime installation]({{site.baseurl}}/docs/troubleshooting/runtime-issues/) \ No newline at end of file