diff --git a/_docs/administration/user-settings.md b/_docs/administration/user-settings.md index c84072d9..2c33c6aa 100644 --- a/_docs/administration/user-settings.md +++ b/_docs/administration/user-settings.md @@ -5,18 +5,20 @@ group: administration toc: true --- -As a user in Codefresh, you can manage the access tokens defined in your account, and optionally, enable access for Codefresh support. +As a user in Codefresh, you can manage your account by authorizing access to your Git provider accounts, and optionally, enabling access for Codefresh support. * Enable access for Codefresh support - Optional. Enable access to your account for troubleshooting purposes. -* Manage Git tokens for authentication +* Authorize Git providers + The Git personal token is a user-specific access token, required to authenticate Git-based actions from Codefresh clients, per provisioned runtime. - The Git personal token is a user-specific access token per provisioned runtime, and is required to authenticate Git-based actions per runtime in Codefresh. - If your admin has set up authentication with OAuth2, you can authorize access to GitHub using OAuth2. - Or, you can always generate a personal access token from GitHub and then add the same to Codefresh to authorize access. + The authorization method depends on the Git provider and on what authorization has been set up by ypur adin. + If your admin has set up authentication with OAuth2, you can authorize access using OAuth2. + Or, you can always generate a personal access token from your Git provider and then add the same to Codefresh to authorize access. + > If you have access to more than one runtime, you can use the same token for multiple runtimes. + You must however authorize access individually for each runtime. ### Enable access for Codefresh support Enable Codefresh support personnel to access your user account. Access to your account is useful for visibility during troubleshooting. @@ -38,77 +40,87 @@ You can disable this security setting at any time. max-width="50%" %} +### Authorize Git access with OAuth or personal access tokens +Authorize Git access with OAuth2 if your account admin has set up Codefresh as an OAuth application, or alternatively through personal access tokens from your Git provider. +* For OAuth2: The adminstrator pre-configures the permissions and expiry date. Once you supply your credentials for authorization, you are automatically directed to the Git Personal Tokens page. +#### Generate personal access token for GitHub -### Update/delete Git personal access tokens -Update your Git personal access token for hosted and hybrid runtimes when needed from the User Settings page. -To authorize with OAuth2, you have to supply your credentials. When authorized, you are automatically directed to the Git Personal Tokens page. +#### Authorize access for Bitbucket +Bitbucket requires your Bitbucket account name and a personal access token to authorize access. -* For OAuth2, the permissions and expiry date are pre-configured by the administrator. -* For Git personal access tokens, when generating a new token, make sure you select `repo` scope for commits and other actions. +**Generate personal access token** +1. Log in to your Bitbucket Cloud or Server account. +1. Select **Manage account > Account settings > Personal access tokens**. +1. Select these scopes: `repository write`,`Project read`. +1. Copy the personal access token generated as you will need it to authorize access. -> If you need access to more than one runtime, you can use the same token for multiple runtimes. -You must however authorize GitHub access or add the personal access token individually for each runtime. +**How to** +1. In the Codefresh UI, go to [User Settings](https://g.codefresh.io/2.0/user-settings){:target="\_blank"}. +1. Select the runtime, and then select one of the following: + * To add a token, select **Add Token**. + * To update an existing token by replacing it with a new token, select **Update Token**. +1. From the **Select Git provider** drop-down, select **Bitbucket**. +1. In the **Bitbucket username field**, enter the username of your Bitbucket account. +1. In the **Bitbucket Personal Access Token** field, paste the token you generated. + -{% include - image.html - lightbox="true" - file="/images/getting-started/github-pat.png" - url="/images/getting-started/github-pat.png" - alt="Permissions for Git personal token" - caption="Permissions for Git personal token" - max-width="50%" -%} -To authorize with OAuth2, you have to supply your credentials. When authorized, you are automatically directed to the Git Personal Tokens page. +{:start="6"} +1. Click **Add Token**. + In the Git Personal Access Tokens list, you can see that the new token is assigned to the runtime. -**Before you begin** -* To use a Git PAT, generate a valid personal access token from your Git provider +#### Authorize access for GitHub +**Before you begin** +Make sure you have: +* For Bitbucket only, your Bitbucket account username +* If needed, a _personal access token_ with the required scopes: + * [GitHub]({{site.baseurl}}/docs/reference/git-tokens/#github-tokens) + * [GitLab]({{site.baseurl}}/docs/reference/git-tokens/#gitlab-tokens) + * [Bitbucket]({{site.baseurl}}/docs/reference/git-tokens/#bitbucket-tokens) -**How to** -1. In the CSDP UI, go to [User Settings](https://g.codefresh.io/2.0/user-settings){:target="\_blank"}. + +**How to** +1. In the Codefresh UI, go to [User Settings](https://g.codefresh.io/2.0/user-settings){:target="\_blank"}. 1. Select the runtime, and then select one of the following: * To add a token, select **Add Token**. * To update an existing token by replacing it with a new token, select **Update Token**. - * To delete an existing token, select **Delete Token**. 1. For OAuth2: - * In the Add Token panel, click **Authorize Access to GitHub**. - > If the application is not registered, you get an error. For example, _Git app not registered_. Contact your admin for help. - * Enter your credentials, and select **Sign In**. - * Complete the verification, for example, if you two-factor authentication is configured. + > If the application is not registered, the button is disabled. Contact your admin for help. + * Click **Authorize Access to GitHub**. + * Enter your credentials, and select **Sign In**. + * Complete the verification if required, as when two-factor authentication is configured, for example. + +{:start="4"} +1. For Git personal access tokens: + * Expand **Advanced authorization options**. + + * In the **Git Personal Access Token** field, paste the token you generated. - {% include - image.html - lightbox="true" - file="/images/administration/user-settings/oauth-user-authentication.png" - url="/images/administration/user-settings/oauth-user-authentication.png" - alt="Authorizing access with OAuth2" - caption="Authorizing access with OAuth2" - max-width="30%" - %} - + -{:start="4"} -1. For Git personal access tokens: - Paste the generated token in the **Token** field, and select **+Add Token**. +{:start="5"} +1. Click **Add Token**. + In the Git Personal Access Tokens list, you can see that the new token is assigned to the runtime. + + + + + +{::nomarkdown} +
+{:/} + - {% include - image.html - lightbox="true" - file="/images/administration/user-settings/user-settings-pat.png" - url="/images/administration/user-settings/user-settings-pat.png" - alt="Adding a Git personal access token" - caption="Adding a Git personal access token" - max-width="30%" - %} + -The token is generated and you are redirected to the User Settings page where you can see the new Git token assigned to the runtime. + ### Related articles [Git tokens in Codefresh]({{site.baseurl}}/docs/reference/git-tokens/) \ No newline at end of file diff --git a/_docs/reference/git-tokens.md b/_docs/reference/git-tokens.md index 603d50f1..a8e28e3d 100644 --- a/_docs/reference/git-tokens.md +++ b/_docs/reference/git-tokens.md @@ -10,53 +10,73 @@ toc: true Codefresh requires two types of Git tokens for authentication: -* A token per runtime (Git runtime token) -* A personal access token for each runtime, unique to every user (Git user token) +* Git runtime token for runtime installation + Used by: + * Argo CD clone repositories and pull changes to sync the desired state in Git to the live state on the cluster. + * Argo Events to create webhooks in Git repositories for Event Sources in Delivery Pipelines + + The Git runtime token is runtime-specific but not user-specific. + + +* Git user token, a user-specific personal access token for each runtime, unique to every user + Unique to every user, the Git user token is used to authenticate the user for client-based actions, such as Git clone and push operations on specific repositories. + Git user token requirements translate to permission scopes which differ for the different Git providers. + + After installation, you need to authorize Git access for every provisioned runtime either through OAuth2 or through a personal access token from your Git provider. + Every user can view the list of runtimes and tokens assigned to each runtime in [User Settings](https://g.codefresh.io/2.0/user-settings){:target="\_blank"}. Codefresh flags and notifies you of invalid, revoked, or expired tokens. + + -You can update expired, revoked, or invalid Git runtime and personal user tokens. ### Git runtime tokens -The Git runtime token is required to provision Codefresh runtimes. The Git runtime token is specific to a runtime, and is mandatory for runtime installation. -An expired, revoked, or invalid Git runtime token is flagged by a notification in the UI. You can then generate a new Git runtime token from your Git provider, and update it in Codefresh. +The Git runtime token is mandatory for runtime installation. -#### Git runtime token permissions -Git runtime tokens need both repo and admim repo access to create webhooks for Git events. +{::nomarkdown} +
+{:/} -{% include - image.html - lightbox="true" - file="/images/getting-started/quick-start/quick-start-git-event-permissions.png" - url="/images/getting-started/quick-start/quick-start-git-event-permissions.png" - alt="Permissions for Git runtime token" - caption="Permissions for Git runtime token" - max-width="60%" - %} +#### GitHub and GitHub Enterprise runtime token scopes + +* `repo` +* `admin:repo_hook` + +{::nomarkdown} +
+{:/} -#### How to update a Git runtime token -Update Git runtime tokens when needed. +#### GitLab Cloud and GitLab Server runtime token scopes -**Before you begin** -* Generate a new runtime token with the correct permissions +* `api` +* `read_repository` -**How to** +{::nomarkdown} +
+{:/} -1. In the Codefresh UI, when you see a notification, select **[Update Token]**. - In the **Runtimes** page, runtimes with invalid tokens are prefixed by the key icon. Mouse over shows invalid token. -1. Select the runtime, and then on the top-right of the page, select and then **+Add Token**. -1. Paste the generated personal access token. -1. If there are no validation errors, select **Add**. +#### Bitbucket Cloud & Bitbucket Server runtime token scopes + +* `Project admin` +* `Repository write` +* `Project read` + +{::nomarkdown} +

+{:/} ### Git personal tokens -The Git personal token is a user-specific personal access token per provisioned runtime. Unique to each user, it is required to authenticate Git-based actions per runtime in Codefresh. -If not provided during runtime installation, user can add personal access tokens (PATs) after installation through [User Settings](https://g.codefresh.io/2.0/user-settings){:target="\_blank"} in the UI, using either OAuth to authorize access or generate one from GitHub. +The Git personal token is a user-specific personal access token per provisioned runtime. Unique to each user, it is required after installation to authenticate Git-based actions per runtime in Codefresh. -If users have access to multiple runtimes, they can use the same personal access token for all the runtimes. -> Users must configure the token for each runtime. +> If you have access to multiple runtimes, you can use the same personal access token for all the runtimes. + You must configure the token for each runtime. -#### Git personal token permissions -Git personal tokens need repo access for commits and other actions. +{::nomarkdown} +
+{:/} -{% include +#### GitHub & GitHub Enterprise personal user token scopes +* `repo` + + +{::nomarkdown} +
+{:/} + +#### GitLab Cloud & GitLab Server personal user token scopes + +* `write_repository` (includes `read-repository`) +* `api-read` + +{::nomarkdown} +
+{:/} + +#### Bitbucket Cloud & Bitbucket Server personal user token scopes + +* `Project read` +* `Repository write` ### Related articles [User settings]({{site.baseurl}}/docs/administration/user-settings/) \ No newline at end of file diff --git a/_docs/runtime/monitor-manage-runtimes.md b/_docs/runtime/monitor-manage-runtimes.md index 5c2cebe6..b71188a0 100644 --- a/_docs/runtime/monitor-manage-runtimes.md +++ b/_docs/runtime/monitor-manage-runtimes.md @@ -9,12 +9,18 @@ toc: true --- -The **Runtimes** page displays the provisioned runtimes in your account, both hybrid, and the hosted runtime if you have one. View runtime components and information in List or Topology view formats. Managed provisioned runtimes in the view mode that suits you. +The **Runtimes** page displays the provisioned runtimes in your account, both hybrid, and the hosted runtime if you have one. +Select the view mode to view runtime components and information, and manage provisioned runtimes in the view mode that suits you. > Unless specified otherwise, management options are common to both hybrid and hosted runtimes. -To monitor provisioned hybrid runtimes, including recovering runtimes for failed clusters, see [Monitor provisioned hybrid runtimes]({{site.baseurl}}/docs/runtime/monitoring-troubleshooting/). +* Add managed clusters to hybrid or hosted runtimes (see [Adding & managing external clusters]({{site.baseurl}}/docs/runtime/managed-cluster/)) +* Add and manage Git Sources associated with hybrid or hosted runtimes (see [Adding & managing Git Sources]({{site.baseurl}}/docs/runtime/git-sources/)) +* Upgrade provisioned hybrid runtimes +* Uninstall hybrid or hosted runtimes +* Update Git runtime tokens +To monitor provisioned hybrid runtimes, including recovering runtimes for failed clusters, see [Monitor provisioned hybrid runtimes]({{site.baseurl}}/docs/runtime/monitoring-troubleshooting/). ### Runtime views @@ -76,16 +82,8 @@ Here is a description of the information in the Topology view. |**Health/Sync status** |The health and sync status of the runtime or cluster. {::nomarkdown} {:/} | |**Search and View options** | {::nomarkdown} {:/}| -### Hybrid/hosted runtime management -Work in either the List or Topology views to manage provisioned runtimes. If an option is valid only for hybrid runtimes, it is indicated as such. - -* Add managed clusters to hybrid or hosted runtimes (see [Adding & managing external clusters]({{site.baseurl}}/docs/runtime/managed-cluster/)) -* Add and manage Git Sources associated with hybrid or hosted runtimes (see [Adding & managing Git Sources]({{site.baseurl}}/docs/runtime/git-sources/)) -* Upgrade provisioned hybrid runtimes -* Uninstall hybrid or hosted runtimes - -#### (Hybrid) Upgrade provisioned runtimes +### (Hybrid) Upgrade provisioned runtimes Upgrade provisioned hybrid runtimes to install critical security updates or to install the latest version of all components. Upgrade a provisioned hybrid runtime by running a silent upgrade or through the CLI wizard. If you have managed clusters for the hybrid runtime, upgrading the runtime automatically updates runtime components within the managed cluster as well. @@ -161,7 +159,7 @@ For both silent or CLI-wizard based upgrades, make sure you have: * To manually define the shared configuration repo, add the `--shared-config-repo` flag with the path to the repo. 1. Confirm to start the upgrade. -#### Uninstall provisioned runtimes +### Uninstall provisioned runtimes Uninstall provisioned hybrid and hosted runtimes that are not in use. Uninstall a runtime by running a silent uninstall, or through the CLI wizard. > Uninstalling a runtime removes the Git Sources and managed clusters associated with the runtime. @@ -227,6 +225,67 @@ Pass the mandatory flags in the uninstall command: 1. If you get errors, run the uninstall command again, with the `--force` flag. + +### Update Git runtime tokens + +Provisioned runtimes require valid Git tokens to authenticate the runtimes. + +There are two different situations when you need to updating Git runtime tokens: +* Update invalid, revoked, or expired tokens: Codefresh automatically flags runtimes with such tokens. It is mandatory to update the Git tokens for these runtimes to continue working with the platform. +* Update valid tokens: Optional. You may want to update Git runtime tokens, even valid runtime tokens, by deleting the existing token and replacing it with a new runtime token. + +The methods for updating any Git runtime token is the same regardless of the reason for the update: +* OAuth2 authorization, if your admin has registered an OAuth Application for Codefresh +* Git access token authentication, by generating a personal access token in your Git provider account with the correct permissions + +**Before you begin** +* To authenticate through a Git access token, generate an access token for the runtime with the correct scopes: `repo` and `admin-repo` + +**How to** +1. Do one of the following: + * If you see a notification in the Codefresh UI about invalid runtime tokens, click **[Update Token]**. + In the Runtimes page, you can see runtimes with invalid tokens are prefixed by the key icon. Mouse over shows invalid token. + * To update an existing runtime token, go to [Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. +1. Select the runtime for which to update the Git token. +1. From the context menu with the additional actions at the top-right, select **Update Git Runtime token**. + + {% include + image.html + lightbox="true" + file="/images/runtime/update-git-runtime-token.png" + url="/images/runtime/update-git-runtime-token.png" + alt="Update Git runtime token option" + caption="Update Git runtime token option" + max-width="40%" +%} + +{:start="4"} +1. Do one of the following: + * If your admin has set up OAuth access, click **Authorize Access to Git Provider**. Go to _step 5_. + * Alternatively, authenticate with an access token from your Git provider. Go to _step 6_. + +{:start="5"} +1. For OAuth2 authorization: + > If the application is not registered, you get an error. Contact your admin for help. + * Enter your credentials, and select **Sign In**. + * If required, as for example if two-factor authentication is configured, complete the verification. + + {% include + image.html + lightbox="true" + file="/images/administration/user-settings/oauth-user-authentication.png" + url="/images/administration/user-settings/oauth-user-authentication.png" + alt="Authorizing access with OAuth2" + caption="Authorizing access with OAuth2" + max-width="30%" + %} + +{:start="6"} +1. For Git token authentication, expand **Advanced authorization options**, and then paste the generated token in the **Git runtime token** field. + +1. Click **Update Token**. + + ### Related articles [Monitor provisioned hybrid runtimes]({{site.baseurl}}/docs/runtime/monitoring-troubleshooting/) [Add Git Sources to runtimes]({{site.baseurl}}/docs/runtime/git-sources/) diff --git a/images/runtime/update-git-runtime-token.png b/images/runtime/update-git-runtime-token.png new file mode 100644 index 00000000..dc3e1e67 Binary files /dev/null and b/images/runtime/update-git-runtime-token.png differ