diff --git a/.github/workflows/qaqc.yaml b/.github/workflows/qaqc.yaml index 87d0160..59c92e1 100644 --- a/.github/workflows/qaqc.yaml +++ b/.github/workflows/qaqc.yaml @@ -21,9 +21,9 @@ jobs: run: | pip install nb-clean==2.0.2 - - name: Ensure clean notebooks - run: | - python .github/workflows/ensure_clean_notebooks.py + # - name: Ensure clean notebooks + # run: | + # python .github/workflows/ensure_clean_notebooks.py # NOTE: this isn't a comprehensive spellcheck, just common typos - name: Spellcheck diff --git a/book/_toc.yml b/book/_toc.yml index 4b41246..e52de32 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -13,6 +13,7 @@ parts: - file: preliminary/what-to-expect - file: preliminary/code-of-conduct - file: preliminary/checklist + - file: preliminary/git # - file: presentations/hackweek/cryocloud_overview/CryoCloud_demo # title: CryoCloud Overview - caption: Presentations diff --git a/book/img/git-gui-credentials.png b/book/img/git-gui-credentials.png new file mode 100644 index 0000000..736182e Binary files /dev/null and b/book/img/git-gui-credentials.png differ diff --git a/book/preliminary/git.md b/book/preliminary/git.md index b3b7764..c7f0364 100644 --- a/book/preliminary/git.md +++ b/book/preliminary/git.md @@ -1,4 +1,4 @@ -# Setting up `git` +# Setting up Git ## What is Git? @@ -12,41 +12,40 @@ You are not required to know Git in advance of this event, but this is a great o ## Setting up on JupyterHub -Below are instructions to get you setup with `git` on the {{hackweek}} -JupyterHub. These are only basic instructions to get started. See the +Below are instructions to get you setup with Git on the {{ hackweek }} container image +running on CryoCloud. These are only basic instructions to get started. See the [Software Carpentry Git](https://swcarpentry.github.io/git-novice/index.html) instructions for a thorough explanation and background information. ### 1. Login to JupyterHub -Go to {{ jupyterhub_url }}. See also our JupyterHub documentation: {ref}`accessing-jupyterhub` +Go to {{ jupyterhub_url }}. ### 2. Open a Terminal -Choose the "Terminal" app from the "Other" options in the Launcher. +Choose the "**Terminal**" app from the "Other" options in the Launcher. ![jupyterlab](../img/jupyter-terminal.png) -### 3. Configure Basic `git` Information +### 3. Configure Basic Information Set your name and email address. The `user.name` is your full name, not your "username" on GitHub or anywhere else. The email address should be one registered on your GitHub account. ```{attention} Use your own name instead of the placeholder `Attendee Name` -in the below commands. For the email, it should be the address you used to create -your GitHub account instead of `attendee@hackweek.com`. Both values need to be +in the below commands. For the email, it should be an address you use with +your GitHub account instead of `attendee@example.com`. Both values need to be surrounded by quotes `"`. ``` ```shell $ git config --global user.name "Attendee Name" -$ git config --global user.email "attendee@hackweek.com" +$ git config --global user.email "attendee@example.com" $ git config --global pull.rebase false ``` -The third line is a configuration you must set before pulling with git. It specifies -the strategy on how git will apply changes you pull from a remote git repository. +The third line configures the strategy git will apply to changes you pull from a remote git repository. More on strategies is [described here.](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) To verify that you successfully executed the above commands, use the `git config --list` command @@ -54,19 +53,46 @@ in the Terminal. The output should look similar to this: ```shell $ git config --list user.name=Attendee Name -user.email=attendee@hackweek.com +user.email=attendee@example.com pull.rebase=false ``` ### 4. Authenticating with GitHub -In order to interact with GitHub via the `git` command inside the JupyterHub environment, -you need to set up authentication. The two methods below both rely on secure -Personal Access Tokens, which you can learn more about on [GitHub docs][gh-docs]. +In order to interact with GitHub via the `git` command in the Terminal or the Git panel in JupyterLab, +you need to set up authentication. We describe three methods below. The first two rely on +Personal Access Tokens (PATs), which you can learn about in the [GitHub PAT docs][gh-pat]. +The difference between these first two is whether you create your own PAT or use a GitHub App to manage PATs. +The third method uses SSH key pairs, which you can learn a lot about in the [GitHub SSH docs][gh-ssh]. -[gh-docs]:https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens +[gh-ssh]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh +[gh-pat]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens -#### Option 1: CryoCloud GitHub Access +#### Option 1: Manual PAT Configuration + +Open up the instructions on the +[GitHub personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) +page. +When you've gotten through it all, GitHub will have created a token, but you have to save it before navigating away. Treat it like you would any password, and know that the token won't be visible again! + +For this hackweek, check the full repo scope as shown in this screenshot: + +![github-token](../img/github-token.png) + +To use the PAT, you need Git to do something that requires authentication, such as pushing to a repository or cloning a private repository. +These actions will prompt for credentials. +**Use the PAT instead of your GitHub password**. + +If you use the Git panel in JupyterLab, be sure to check "**Save my login temporarily**"! + +![git gui credentials](../img/git-gui-credentials.png) + +```{attention} +The Terminal prompt for the `Password:` will not show any characters that are entered +and stay blank. Make sure to only paste in your token once and then hit the enter key. +``` + +#### Option 2: GitHub Scoped Credentials We recommend this method if you have permission to configure a GitHub App on the user or organization where you need to authenticate. For instance, if you want to push to `https://github.com/example/repo.git`, then you need to have @@ -97,28 +123,36 @@ showing the Terminal way just described. ![gh-scoped-creds](https://miro.medium.com/v2/resize:fit:720/format:webp/1*B3qjACXLBG9pBOlzY8WNxA.gif) -#### Option 2: Manual Configuration +#### Option 3: SSH Key Pair -Work through the instructions on the -[GitHub personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) -page. The maximum permissions you likely need is the **repo** scope. +This method generates a private and public SSH key in your personal `~/.ssh` folder. +Note that your secrets may not be as secure with your personal folder residing in the commercial cloud, so we recommend using a passphrase with your SSH key pair. -![github-token](../img/github-token.png) +To generate the pair, run the following Terminal command, press enter to accept the default location, and then create a passphrase when prompted. +You will need to use that passphrase, so treat it like any other password. + +```shell +ssh-keygen -t ed25519 -C "jovyan@cryocloud" +``` -Once you have created your token, be sure to save it or use it before navigating away. It won't be -visible again. To have it saved on CryoCloud the first time you use it, configure the `git` credential helper. +Everytime you restart your JupyterLab server, you need to unlock your private key before using the Git panel in JupyterLab. ```shell -git config --global credential.helper store +ssh-add ~/.ssh/id_ed25519 ``` -To use the Personal Access Token, you need to use `git` to do something that requires authentication, such as -pushing to a repository or cloning a private repository. These actions will prompt -for input of your credentials. When prompted for a password, use the Personal Access Token rather than your -GitHub password. +Next, copy the string printed by the Terminal command `cat ~/.ssh/id_ed25519.pub`. +That is the public key you can share with GitHub. -```{attention} -The prompt for the `Password:` will not show any characters that are entered -and stay blank. Make sure to only copy and paste your token once and then -hit the enter key. +1. Go to "Settings" > "SSH and GPG keys" in your GitHub [profile](https://github.com/settings/keys). +1. Click the "**New SSH key**" button. +1. Ignore the "**Title**" field. +1. Paste the entire `~/.ssh/id_ed25519.pub` contents in the "**Key**" field and click "**Add SSH key**". + +Now verify that your key is unlocked and copied to GitHub by trying the following back in your Terminal. + +```shell +ssh -T git@github.com ``` + +The command should succeed without prompting for your passphrase. \ No newline at end of file