gapicgen: simplify setup and documentation.
The cookie name used for gerrit authentication is standard, and so this
change sets the default to that value ("o") and removes references to it
in documentation.
This PR also attempts to clarify what the relevant auth token from
Gerrit code review looks like in the documentation, in hopes that future
users don't get tripped on this as much.
Change-Id: Ied4f780f1246b4269ba3f9c48e6958ec57593687
Reviewed-on: https://code-review.googlesource.com/c/gocloud/+/50611
Reviewed-by: kokoro <noreply+kokoro@google.com>
Reviewed-by: Alex Hong <hongalex@google.com>
diff --git a/internal/gapicgen/cmd/genbot/README.md b/internal/gapicgen/cmd/genbot/README.md
index 2bc686e..657acf2 100644
--- a/internal/gapicgen/cmd/genbot/README.md
+++ b/internal/gapicgen/cmd/genbot/README.md
@@ -5,8 +5,25 @@
## Getting certs
-1. Grab github personal access token (see: https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)
-1. Grab a gerrit HTTP auth cookie at https://code-review.googlesource.com/settings/#HTTPCredentials > Obtain password > `git-your@email.com=SomeHash....`
+This tool relies on API authentication for both github (which hosts the `google.golang.org/genproto/...` libraries) and the
+Gerrit code review instance `code-review.googlesource.com` which is where the `cloud.google.com/go/...` libraries are maintained.
+
+You need to supply credentials for both systems to successfully manage the generation of gapic libraries.
+
+### Github
+
+For Github, you need to generate/supply a Personal Access Token. More information on how that's done is here:
+https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line
+
+### Gerrit
+
+For Gerrit, you need a gerrit authentication cookie. The authentication flow in gerrit to fetch this information begins here:
+https://code-review.googlesource.com/settings/#HTTPCredentials
+
+At the end, it provides a shell script for injecting the cookies into your .gitcookies file. There's typically two cookies in the provided shell script, one for code.googlesource.com and one for code-review.googlesource.com (though there is an option to generate a single cookie for the entire domain as well). You want the cookie correspnding to code-review.googlesource.com.
+
+The relevant portion which needs to be passed to this tool looks similar to this (you need both the identity and the secret):
+**git-yourlogin.yourdomain.com=1//abcdef01010209202-cbdef010102-skdjskljsdkjsksjd**
## Running locally
@@ -26,7 +43,6 @@
--githubUsername=$GITHUB_USERNAME \
--githubName="Jean de Klerk" \
--githubEmail=deklerk@google.com \
- --gerritCookieName=o \
--gerritCookieValue=<cookie>
```
@@ -46,7 +62,6 @@
-e "GITHUB_USERNAME=jadekler" \
-e "GITHUB_NAME=\"Jean de Klerk\"" \
-e "GITHUB_EMAIL=deklerk@google.com" \
- -e "GERRIT_COOKIE_NAME=o" \
-e "GERRIT_COOKIE_VALUE=<cookie>" \
genbot
```
diff --git a/internal/gapicgen/cmd/genbot/main.go b/internal/gapicgen/cmd/genbot/main.go
index 1f348a1..e7d047b 100644
--- a/internal/gapicgen/cmd/genbot/main.go
+++ b/internal/gapicgen/cmd/genbot/main.go
@@ -45,7 +45,7 @@
githubUsername = flag.String("githubUsername", "", "ex -githubUsername=jadekler")
githubName = flag.String("githubName", "", "ex -githubName=\"Jean de Klerk\"")
githubEmail = flag.String("githubEmail", "", "ex -githubEmail=deklerk@google.com")
- gerritCookieName = flag.String("gerritCookieName", "", "ex: -gerritCookieName=o")
+ gerritCookieName = flag.String("gerritCookieName", "o", "ex: -gerritCookieName=o")
gerritCookieValue = flag.String("gerritCookieValue", "", "ex: -gerritCookieValue=git-your@email.com=SomeHash....")
usage = func() {
@@ -54,7 +54,6 @@
-githubUsername=jadekler \
-githubEmail=deklerk@google.com \
-githubName="Jean de Klerk" \
- -gerritCookieName=o \
-gerritCookieValue=git-your@email.com=SomeHash....
-githubAccessToken
@@ -70,7 +69,7 @@
The email to use in the github commit.
-gerritCookieName
- The name of the cookie. Almost certainly "o".
+ The name of the cookie. Almost certainly "o" (the default).
-gerritCookieValue
The value of the gerrit cookie. Probably looks like "git-your@email.com=SomeHash....". Get this at https://code-review.googlesource.com/settings/#HTTPCredentials > Obtain password > "git-your@email.com=SomeHash....".`)
diff --git a/internal/gapicgen/cmd/genmgr/README.md b/internal/gapicgen/cmd/genmgr/README.md
index 5ba9146..f81539f 100644
--- a/internal/gapicgen/cmd/genmgr/README.md
+++ b/internal/gapicgen/cmd/genmgr/README.md
@@ -18,8 +18,25 @@
## Getting certs
-1. Grab github personal access token (see: https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)
-2. Grab a gerrit HTTP auth cookie at https://code-review.googlesource.com/settings/#HTTPCredentials > Obtain password > `git-your@email.com=SomeHash....`
+This tool relies on API authentication for both github (which hosts the `google.golang.org/genproto/...` libraries) and the
+Gerrit code review instance `code-review.googlesource.com` which is where the `cloud.google.com/go/...` libraries are maintained.
+
+You need to supply credentials for both systems to successfully manage the generation of gapic libraries.
+
+### Github
+
+For Github, you need to generate/supply a Personal Access Token. More information on how that's done is here:
+https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line
+
+### Gerrit
+
+For Gerrit, you need a gerrit authentication cookie. The authentication flow in gerrit to fetch this information begins here:
+https://code-review.googlesource.com/settings/#HTTPCredentials
+
+At the end, it provides a shell script for injecting the cookies into your .gitcookies file. There's typically two cookies in the provided shell script, one for code.googlesource.com and one for code-review.googlesource.com (though there is an option to generate a single cookie for the entire domain as well). You want the cookie correspnding to code-review.googlesource.com.
+
+The relevant portion which needs to be passed to this tool looks similar to this (you need both the identity and the secret):
+**git-yourlogin.yourdomain.com=1//abcdef01010209202-cbdef010102-skdjskljsdkjsksjd**
## Running locally
@@ -31,7 +48,6 @@
--githubAccessToken=11223344556677889900aabbccddeeff11223344 \
--githubName="Jean de Klerk" \
--githubEmail=deklerk@google.com \
- --gerritCookieName=o \
--gerritCookieValue=<cookie>
```
@@ -48,7 +64,6 @@
-e "GITHUB_ACCESS_TOKEN=11223344556677889900aabbccddeeff11223344" \
-e "GITHUB_NAME=\"Jean de Klerk\"" \
-e "GITHUB_EMAIL=deklerk@google.com" \
- -e "GERRIT_COOKIE_NAME=o" \
-e "GERRIT_COOKIE_VALUE=<cookie>" \
genmgr
```
diff --git a/internal/gapicgen/cmd/genmgr/main.go b/internal/gapicgen/cmd/genmgr/main.go
index 34b9a14..43c8d7d 100644
--- a/internal/gapicgen/cmd/genmgr/main.go
+++ b/internal/gapicgen/cmd/genmgr/main.go
@@ -41,13 +41,12 @@
githubAccessToken = flag.String("githubAccessToken", "", "Get an access token at https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line")
githubName = flag.String("githubName", "", "ex -githubName=\"Jean de Klerk\"")
githubEmail = flag.String("githubEmail", "", "ex -githubEmail=deklerk@google.com")
- gerritCookieName = flag.String("gerritCookieName", "", "ex: -gerritCookieName=o")
+ gerritCookieName = flag.String("gerritCookieName", "o", "ex: -gerritCookieName=o")
gerritCookieValue = flag.String("gerritCookieValue", "", "ex: -gerritCookieValue=git-your@email.com=SomeHash....")
usage = func() {
fmt.Fprintln(os.Stderr, `genmgr \
-githubAccessToken=11223344556677889900aabbccddeeff11223344 \
- -gerritCookieName=o \
-gerritCookieValue=git-your@email.com=SomeHash....
-githubAccessToken
@@ -60,7 +59,7 @@
The email to use in the github commit.
-gerritCookieName
- The name of the cookie. Almost certainly "o".
+ The name of the cookie. Almost certainly "o" (the default).
-gerritCookieValue
The value of the gerrit cookie. Probably looks like "git-your@email.com=SomeHash....". Get this at https://code-review.googlesource.com/settings/#HTTPCredentials > Obtain password > "git-your@email.com=SomeHash....".`)
