Skip to content

Commit d91f9ac

Browse files
billiegoosebilliegoose
authored
Simplify auth (#13)
1 parent 6f7dfbd commit d91f9ac

File tree

11 files changed

+158
-72
lines changed

11 files changed

+158
-72
lines changed

‎docs/alphabetic.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ sidebar_label: Alphabetical Index
2929
##### [resolveRef](resolveRef.md)
3030
##### [sign](sign.md)
3131
##### [status](status.md)
32-
##### [utils.auth](utils_auth.md)
33-
##### [utils.oauth2](utils_oauth2.md)
32+
##### [utils.auth](utils_auth.md) [deprecated]
33+
##### [utils.oauth2](utils_oauth2.md) [deprecated]
3434
##### [verify](verify.md)
3535
##### [version](version.md)

‎docs/authentication.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: Authentication
3+
sidebar_label: Authentication
4+
---
5+
6+
Authentication is normally required for [`push`](./push.html)ing to a git repository.
7+
It may also be required to [`clone`](./clone.html) or [`fetch`](./fetch.html) from a private repository.
8+
Git does all its authentication using HTTPS Basic Authentication.
9+
Usually this is straightforward: just specify `username` and `password`.
10+
11+
```js
12+
await git.push({
13+
...repo,
14+
username: 'your username',
15+
password: 'your password'
16+
})
17+
```
18+
19+
However, there are some things to watch out for.
20+
21+
If you have two-factor authentication (2FA) enabled on your account, you
22+
probably cannot push or pull using your regular username and password.
23+
Instead, you may have to create a Personal Access Token (or an App Password in Bitbucket lingo) and use that to authenticate.
24+
( [Instructions for GitHub](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)
25+
| [Instructions for Bitbucket](https://confluence.atlassian.com/bitbucket/app-passwords-828781300.html)
26+
| [Instructions for Gitlab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
27+
)
28+
29+
```js
30+
await git.push({
31+
...repo,
32+
username: 'your username', // Note: username is optional for Github
33+
token: 'your Personal Access Token'
34+
})
35+
```
36+
37+
If you are writing a third-party app that interacts with Github/Gitlab/Bitbucket, you may be obtaining
38+
OAuth2 tokens from the service via a feature like "Login with Github".
39+
Depending on the OAuth2 token's grants, you can use those tokens for pushing and pulling from git repos as well.
40+
Unfortunately, all the major git hosting companies have chosen different conventions for converting
41+
OAuth2 tokens into Basic Authentication headers! Therefore it is necessary to specify which company's
42+
convention you are interacting with via the `oauth2format` parameter.
43+
Currently, the following values are understood:
44+
45+
| oauth2format | Basic Auth username | Basic Auth password |
46+
| ------------ | ------------------- | ------------------- |
47+
| 'github' | `token` | 'x-oauth-basic' |
48+
| 'bitbucket' | 'x-token-auth' | `token` |
49+
| 'gitlab' | 'oauth2' | `token` |
50+
51+
I will gladly accept pull requests to add support for more companies' conventions.
52+
Here is what using OAuth2 authentication looks like.
53+
Note when using OAuth2 tokens, you do not include `username` or `password`.
54+
55+
```js
56+
await git.push({
57+
...repo,
58+
oauth2format: 'gitlab',
59+
token: 'your OAuth2 Token'
60+
})
61+
```
62+
63+
A complete summary of how the four parameters interact to determine the Basic Auth headers is described by the following truth table:
64+
65+
| username | password | token | oauth2format | = Result |
66+
| -------- | -------- | ----- | ------------ | -------------------------------------------------------------------------------- |
67+
| | | | | Basic Auth not used |
68+
| X | | | | Error "Missing token or password" |
69+
| | X | | | Error "Missing username" |
70+
| X | X | | | `{authUsername: username, authPassword: password}` |
71+
| | | X | | `{authUsername: token, authPassword: ''}` (Github's alternative format) |
72+
| X | | X | | `{authUsername: username, authPassword: token}` |
73+
| | X | X | | Error "Cannot mix 'password' with 'token'" |
74+
| X | X | X | | Error "Cannot mix 'password' with 'token'" |
75+
| | | | X | Error "Missing token" |
76+
| X | | | X | Error "Cannot mix 'username' with 'oauth2format'. Missing token." |
77+
| | X | | X | Error "Cannot mix 'password' with 'oauth2format'. Missing token." |
78+
| X | X | | X | Error "Cannot mix 'username' and 'password' with 'oauth2format'. Missing token." |
79+
| | | X | X | as described in the oauth2format table above |
80+
| X | | X | X | Error "Cannot mix 'username' with 'oauth2format' and 'token'" |
81+
| | X | X | X | Error "Cannot mix 'password' with 'oauth2format' and 'token'" |
82+
| X | X | X | X | Error "Cannot mix 'username' and 'password' with 'oauth2format' and 'token'" |

‎docs/clone.md

Lines changed: 15 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,21 @@ sidebar_label: clone
55

66
Clone a repository
77

8-
| param | type [= default] | description |
9-
| ----------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
10-
| **fs**, **dir**, gitdir | FSModule, string, string | The filesystem holding the git repo, the [working tree](dir-vs-gitdir.md) directory path, and optionally the [git directory](dir-vs-gitdir.md) path |
11-
| **url** | string | The URL of the remote repository. |
12-
| ref | string = undefined | Which branch to clone. By default this is the designated "main branch" of the repository. |
13-
| singleBranch | bool = false | Instead of the default behavior of fetching all the branches, only fetch a single branch. |
14-
| noCheckout | bool = false | If true, clone will only fetch the repo, not check out a branch. Skipping checkout can save a lot of time normally spent writing files to disk. |
15-
| remote | string = 'origin' | What to name the remote that is created. The default is 'origin'. |
16-
| authUsername | string = undefined | The username to use with Basic Auth |
17-
| authPassword | string = undefined | The password to use with Basic Auth |
18-
| depth | integer = undefined | Determines how much of the git repository's history to retrieve. |
19-
| since | Date = undefined | Only fetch commits created after the given date. Mutually exclusive with `depth`. |
20-
| exclude | Array\<string\> = [ ] | A list of branches or tags. Instructs the remote server not to send us any commits reachable from these refs. |
21-
| relative | boolean = false | Changes the meaning of `depth` to be measured from the current shallow depth rather than from the branch tip. |
22-
| emitter | EventEmitter = undefined | Listeners to this EventEmitter can receive 'progress' and 'message' events. |
23-
| return | Promise\<void\> | Resolves successfully when clone completes |
24-
25-
> Need to use a Personal Access Token or OAuth? See the [`utils.auth`](utils_auth.html) and [`utils.oauth2`](utils_oauth2.html) functions.
8+
| param | type [= default] | description |
9+
| --------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
10+
| **fs**, **dir**, gitdir | FSModule,&nbsp;string,&nbsp;string | The filesystem holding the git repo, the [working tree](dir-vs-gitdir.md) directory path, and optionally the [git directory](dir-vs-gitdir.md) path |
11+
| username, password, token, oauth2format | string,&nbsp;string,&nbsp;string,&nbsp;string | See the [Authentication](./authentication.html) documentation |
12+
| **url** | string | The URL of the remote repository. |
13+
| ref | string = undefined | Which branch to clone. By default this is the designated "main branch" of the repository. |
14+
| singleBranch | bool = false | Instead of the default behavior of fetching all the branches, only fetch a single branch. |
15+
| noCheckout | bool = false | If true, clone will only fetch the repo, not check out a branch. Skipping checkout can save a lot of time normally spent writing files to disk. |
16+
| remote | string = 'origin' | What to name the remote that is created. The default is 'origin'. |
17+
| depth | integer = undefined | Determines how much of the git repository's history to retrieve. |
18+
| since | Date = undefined | Only fetch commits created after the given date. Mutually exclusive with `depth`. |
19+
| exclude | Array\<string\> = [ ] | A list of branches or tags. Instructs the remote server not to send us any commits reachable from these refs. |
20+
| relative | boolean = false | Changes the meaning of `depth` to be measured from the current shallow depth rather than from the branch tip. |
21+
| emitter | EventEmitter = undefined | Listeners to this EventEmitter can receive 'progress' and 'message' events. |
22+
| return | Promise\<void\> | Resolves successfully when clone completes |
2623

2724
To monitor progress, create an EventEmitter, add listeners, and pass into the function as the `emitter` argument.
2825

‎docs/fetch.md

Lines changed: 15 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,21 @@ sidebar_label: fetch
55

66
Fetch commits from a remote repository
77

8-
| param | type [= default] | description |
9-
| ----------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
10-
| **fs**, **dir**, gitdir | FSModule,&nbsp;string,&nbsp;string | The filesystem holding the git repo, the [working tree](dir-vs-gitdir.md) directory path, and optionally the [git directory](dir-vs-gitdir.md) path |
11-
| url | string = undefined | The URL of the remote repository. Will be gotten from gitconfig if absent. |
12-
| ref | string = 'HEAD' | Which branch to fetch. By default this is the currently checked out branch. |
13-
| singleBranch | bool = false | Instead of the default behavior of fetching all the branches, only fetch a single branch. |
14-
| remote | string = 'origin' | What to name the remote that is created. The default is 'origin'. |
15-
| authUsername | string = undefined | The username to use with Basic Auth |
16-
| authPassword | string = undefined | The password to use with Basic Auth |
17-
| depth | integer = undefined | Determines how much of the git repository's history to retrieve. |
18-
| since | Date = undefined | Only fetch commits created after the given date. Mutually exclusive with `depth`. |
19-
| exclude | Array\<string\> = [ ] | A list of branches or tags. Instructs the remote server not to send us any commits reachable from these refs. |
20-
| relative | boolean = false | Changes the meaning of `depth` to be measured from the current shallow depth rather than from the branch tip. |
21-
| tags | boolean = false | Also fetch tags |
22-
| emitter | EventEmitter = undefined | Listeners to this EventEmitter can receive 'progress' and 'message' events. |
23-
| return | Promise\<FetchResponse\> | Resolves successfully when fetch completes |
24-
25-
> Need to use a Personal Access Token or OAuth? See the [`utils.auth`](utils_auth.html) and [`utils.oauth2`](utils_oauth2.html) functions.
8+
| param | type [= default] | description |
9+
| --------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
10+
| **fs**, **dir**, gitdir | FSModule,&nbsp;string,&nbsp;string | The filesystem holding the git repo, the [working tree](dir-vs-gitdir.md) directory path, and optionally the [git directory](dir-vs-gitdir.md) path |
11+
| username, password, token, oauth2format | string,&nbsp;string,&nbsp;string,&nbsp;string | See the [Authentication](./authentication.html) documentation |
12+
| url | string = undefined | The URL of the remote repository. Will be gotten from gitconfig if absent. |
13+
| ref | string = 'HEAD' | Which branch to fetch. By default this is the currently checked out branch. |
14+
| singleBranch | bool = false | Instead of the default behavior of fetching all the branches, only fetch a single branch. |
15+
| remote | string = 'origin' | What to name the remote that is created. The default is 'origin'. |
16+
| depth | integer = undefined | Determines how much of the git repository's history to retrieve. |
17+
| since | Date = undefined | Only fetch commits created after the given date. Mutually exclusive with `depth`. |
18+
| exclude | Array\<string\> = [ ] | A list of branches or tags. Instructs the remote server not to send us any commits reachable from these refs. |
19+
| relative | boolean = false | Changes the meaning of `depth` to be measured from the current shallow depth rather than from the branch tip. |
20+
| tags | boolean = false | Also fetch tags |
21+
| emitter | EventEmitter = undefined | Listeners to this EventEmitter can receive 'progress' and 'message' events. |
22+
| return | Promise\<FetchResponse\> | Resolves successfully when fetch completes |
2623

2724
The object returned has the following schema:
2825

0 commit comments

Comments
 (0)