Skip to content

Commit 5eaff8e

Browse files
NimRegevNimRegev
authored
Cap user authorize access (#243)
* Update git token processes * Update token topics Updated reference and user settings topics for git token (pending new screesnhots) * Update content * Update git-tokens.md * Update git-tokens.md
1 parent 8b67f23 commit 5eaff8e

File tree

4 files changed

+209
-101
lines changed

4 files changed

+209
-101
lines changed

‎_docs/administration/user-settings.md‎

Lines changed: 67 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,20 @@ group: administration
55
toc: true
66
---
77

8-
As a user in Codefresh, you can manage the access tokens defined in your account, and optionally, enable access for Codefresh support.
8+
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.
99

1010
* Enable access for Codefresh support
11-
1211
Optional. Enable access to your account for troubleshooting purposes.
1312

14-
* Manage Git tokens for authentication
13+
* Authorize Git providers
14+
The Git personal token is a user-specific access token, required to authenticate Git-based actions from Codefresh clients, per provisioned runtime.
1515

16-
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.
17-
If your admin has set up authentication with OAuth2, you can authorize access to GitHub using OAuth2.
18-
Or, you can always generate a personal access token from GitHub and then add the same to Codefresh to authorize access.
16+
The authorization method depends on the Git provider and on what authorization has been set up by ypur adin.
17+
If your admin has set up authentication with OAuth2, you can authorize access using OAuth2.
18+
Or, you can always generate a personal access token from your Git provider and then add the same to Codefresh to authorize access.
1919

20+
> If you have access to more than one runtime, you can use the same token for multiple runtimes.
21+
You must however authorize access individually for each runtime.
2022

2123
### Enable access for Codefresh support
2224
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.
3840
max-width="50%"
3941
%}
4042

43+
### Authorize Git access with OAuth or personal access tokens
44+
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.
45+
* 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.
4146

47+
#### Generate personal access token for GitHub
4248

43-
### Update/delete Git personal access tokens
44-
Update your Git personal access token for hosted and hybrid runtimes when needed from the User Settings page.
45-
To authorize with OAuth2, you have to supply your credentials. When authorized, you are automatically directed to the Git Personal Tokens page.
49+
#### Authorize access for Bitbucket
50+
Bitbucket requires your Bitbucket account name and a personal access token to authorize access.
4651

47-
* For OAuth2, the permissions and expiry date are pre-configured by the administrator.
48-
* For Git personal access tokens, when generating a new token, make sure you select `repo` scope for commits and other actions.
52+
**Generate personal access token**
4953

54+
1. Log in to your Bitbucket Cloud or Server account.
55+
1. Select **Manage account > Account settings > Personal access tokens**.
56+
1. Select these scopes: `repository write`,`Project read`.
57+
1. Copy the personal access token generated as you will need it to authorize access.
5058

51-
> If you need access to more than one runtime, you can use the same token for multiple runtimes.
52-
You must however authorize GitHub access or add the personal access token individually for each runtime.
59+
**How to**
60+
1. In the Codefresh UI, go to [User Settings](https://g.codefresh.io/2.0/user-settings){:target="\_blank"}.
61+
1. Select the runtime, and then select one of the following:
62+
* To add a token, select **Add Token**.
63+
* To update an existing token by replacing it with a new token, select **Update Token**.
64+
1. From the **Select Git provider** drop-down, select **Bitbucket**.
65+
1. In the **Bitbucket username field**, enter the username of your Bitbucket account.
66+
1. In the **Bitbucket Personal Access Token** field, paste the token you generated.
5367

68+
<!---add new screenshot> -->
5469

55-
{% include
56-
image.html
57-
lightbox="true"
58-
file="/images/getting-started/github-pat.png"
59-
url="/images/getting-started/github-pat.png"
60-
alt="Permissions for Git personal token"
61-
caption="Permissions for Git personal token"
62-
max-width="50%"
63-
%}
6470

65-
To authorize with OAuth2, you have to supply your credentials. When authorized, you are automatically directed to the Git Personal Tokens page.
71+
{:start="6"}
72+
1. Click **Add Token**.
73+
In the Git Personal Access Tokens list, you can see that the new token is assigned to the runtime.
6674

67-
**Before you begin**
68-
* To use a Git PAT, generate a valid personal access token from your Git provider
75+
#### Authorize access for GitHub
76+
**Before you begin**
77+
Make sure you have:
78+
* For Bitbucket only, your Bitbucket account username
79+
* If needed, a _personal access token_ with the required scopes:
80+
* [GitHub]({{site.baseurl}}/docs/reference/git-tokens/#github-tokens)
81+
* [GitLab]({{site.baseurl}}/docs/reference/git-tokens/#gitlab-tokens)
82+
* [Bitbucket]({{site.baseurl}}/docs/reference/git-tokens/#bitbucket-tokens)
6983

70-
**How to**
71-
1. In the CSDP UI, go to [User Settings](https://g.codefresh.io/2.0/user-settings){:target="\_blank"}.
84+
85+
**How to**
86+
1. In the Codefresh UI, go to [User Settings](https://g.codefresh.io/2.0/user-settings){:target="\_blank"}.
7287
1. Select the runtime, and then select one of the following:
7388
* To add a token, select **Add Token**.
7489
* To update an existing token by replacing it with a new token, select **Update Token**.
75-
* To delete an existing token, select **Delete Token**.
7690
1. For OAuth2:
77-
* In the Add Token panel, click **Authorize Access to GitHub**.
78-
> If the application is not registered, you get an error. For example, _Git app not registered_. Contact your admin for help.
79-
* Enter your credentials, and select **Sign In**.
80-
* Complete the verification, for example, if you two-factor authentication is configured.
91+
> If the application is not registered, the button is disabled. Contact your admin for help.
92+
* Click **Authorize Access to GitHub**.
93+
* Enter your credentials, and select **Sign In**.
94+
* Complete the verification if required, as when two-factor authentication is configured, for example.
95+
<!---add new screenshot> -->
8196

97+
{:start="4"}
98+
1. For Git personal access tokens:
99+
* Expand **Advanced authorization options**.
100+
<!---* For Bitbucket, enter your **Bitbucket username**. -->
101+
* In the **Git Personal Access Token** field, paste the token you generated.
82102

83-
{% include
84-
image.html
85-
lightbox="true"
86-
file="/images/administration/user-settings/oauth-user-authentication.png"
87-
url="/images/administration/user-settings/oauth-user-authentication.png"
88-
alt="Authorizing access with OAuth2"
89-
caption="Authorizing access with OAuth2"
90-
max-width="30%"
91-
%}
92-
103+
<!---add new screenshot> -->
93104

94105

95-
{:start="4"}
96-
1. For Git personal access tokens:
97-
Paste the generated token in the **Token** field, and select **+Add Token**.
106+
{:start="5"}
107+
1. Click **Add Token**.
108+
In the Git Personal Access Tokens list, you can see that the new token is assigned to the runtime.
109+
110+
111+
112+
113+
114+
{::nomarkdown}
115+
<br>
116+
{:/}
117+
98118

99-
{% include
100-
image.html
101-
lightbox="true"
102-
file="/images/administration/user-settings/user-settings-pat.png"
103-
url="/images/administration/user-settings/user-settings-pat.png"
104-
alt="Adding a Git personal access token"
105-
caption="Adding a Git personal access token"
106-
max-width="30%"
107-
%}
119+
108120

109121

110-
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.
111122

112123

124+
113125
### Related articles
114126
[Git tokens in Codefresh]({{site.baseurl}}/docs/reference/git-tokens/)

‎_docs/reference/git-tokens.md‎

Lines changed: 71 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -10,61 +10,98 @@ toc: true
1010

1111

1212
Codefresh requires two types of Git tokens for authentication:
13-
* A token per runtime (Git runtime token)
14-
* A personal access token for each runtime, unique to every user (Git user token)
13+
* Git runtime token for runtime installation
14+
Used by:
15+
* Argo CD clone repositories and pull changes to sync the desired state in Git to the live state on the cluster.
16+
* Argo Events to create webhooks in Git repositories for Event Sources in Delivery Pipelines
17+
18+
The Git runtime token is runtime-specific but not user-specific.
19+
20+
21+
* Git user token, a user-specific personal access token for each runtime, unique to every user
22+
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.
23+
Git user token requirements translate to permission scopes which differ for the different Git providers.
24+
25+
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.
26+
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.
27+
28+
1529

16-
You can update expired, revoked, or invalid Git runtime and personal user tokens.
1730

1831
### Git runtime tokens
19-
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.
20-
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.
32+
The Git runtime token is mandatory for runtime installation.
2133

22-
#### Git runtime token permissions
23-
Git runtime tokens need both repo and admim repo access to create webhooks for Git events.
34+
{::nomarkdown}
35+
</br>
36+
{:/}
2437

25-
{% include
26-
image.html
27-
lightbox="true"
28-
file="/images/getting-started/quick-start/quick-start-git-event-permissions.png"
29-
url="/images/getting-started/quick-start/quick-start-git-event-permissions.png"
30-
alt="Permissions for Git runtime token"
31-
caption="Permissions for Git runtime token"
32-
max-width="60%"
33-
%}
38+
#### GitHub and GitHub Enterprise runtime token scopes
39+
40+
* `repo`
41+
* `admin:repo_hook`
42+
43+
{::nomarkdown}
44+
</br>
45+
{:/}
3446

35-
#### How to update a Git runtime token
36-
Update Git runtime tokens when needed.
47+
#### GitLab Cloud and GitLab Server runtime token scopes
3748

38-
**Before you begin**
39-
* Generate a new runtime token with the correct permissions
49+
* `api`
50+
* `read_repository`
4051

41-
**How to**
52+
{::nomarkdown}
53+
</br>
54+
{:/}
4255

43-
1. In the Codefresh UI, when you see a notification, select **[Update Token]**.
44-
In the **Runtimes** page, runtimes with invalid tokens are prefixed by the key icon. Mouse over shows invalid token.
45-
1. Select the runtime, and then on the top-right of the page, select and then **+Add Token**.
46-
1. Paste the generated personal access token.
47-
1. If there are no validation errors, select **Add**.
56+
#### Bitbucket Cloud & Bitbucket Server runtime token scopes
57+
58+
* `Project admin`
59+
* `Repository write`
60+
* `Project read`
61+
62+
{::nomarkdown}
63+
</br></br>
64+
{:/}
4865

4966
### Git personal tokens
50-
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.
51-
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.
67+
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.
5268

53-
If users have access to multiple runtimes, they can use the same personal access token for all the runtimes.
54-
> Users must configure the token for each runtime.
69+
> If you have access to multiple runtimes, you can use the same personal access token for all the runtimes.
70+
You must configure the token for each runtime.
5571

56-
#### Git personal token permissions
57-
Git personal tokens need repo access for commits and other actions.
72+
{::nomarkdown}
73+
</br>
74+
{:/}
5875

59-
{% include
76+
#### GitHub & GitHub Enterprise personal user token scopes
77+
* `repo`
78+
79+
<!---{% include
6080
image.html
6181
lightbox="true"
6282
file="/images/getting-started/github-pat.png"
6383
url="/images/getting-started/github-pat.png"
6484
alt="Permissions for Git personal token"
6585
caption="Permissions for Git personal token"
6686
max-width="60%"
67-
%}
87+
%}-->
88+
{::nomarkdown}
89+
</br>
90+
{:/}
91+
92+
#### GitLab Cloud & GitLab Server personal user token scopes
93+
94+
* `write_repository` (includes `read-repository`)
95+
* `api-read`
96+
97+
{::nomarkdown}
98+
</br>
99+
{:/}
100+
101+
#### Bitbucket Cloud & Bitbucket Server personal user token scopes
102+
103+
* `Project read`
104+
* `Repository write`
68105

69106
### Related articles
70107
[User settings]({{site.baseurl}}/docs/administration/user-settings/)

0 commit comments

Comments
 (0)