-
Notifications
You must be signed in to change notification settings - Fork 0
/
github-setup.qmd
147 lines (103 loc) · 7.45 KB
/
github-setup.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
# Setting up a GitHub Account
It's very easy to get set up on [GitHub](https://Github.com).
Just click the link above and select the package you'd like.
If you have an academic email address, consider making this your primary email address on the account, as it gives you a **PRO** account for free with access to more features.
See [here](https://docs.github.com/en/get-started/learning-about-github/githubs-products) for more details about the differences.
If you are a student, you should also sign up for the [GitHub Student Developer Pack](https://education.github.com/pack) as this gives you free access to a bunch of useful tools, such as the GitKraken Git client mentioned earlier.
If you are a teacher, you get access to a GitHub Teams account, which also comes with its own set of benefits (see [here](https://education.github.com/teachers) for more details).
Be sure to choose a user name that is easy to remember, and easy to find.
I would suggest just using your name, or the username you have for other work-related accounts (e.g., Twitter).
It's quite annoying to try and change this later, so spend a little time thinking about it now.
::: {.callout-note}
You can choose a public-facing name that is different to your username, so you can just use your full name here if yours is long and you don't want to use it as your username.
:::
Now you have a GitHub account set up, this is your **remote**.
If you work on a project with collaborators, this can be shared with them.
That way, collaborators can work on their own versions of the code on their **local** machine (computer), and when it's ready for other people to use/help write, they can `push` it to the **remote** where others can access it.
Don't worry if you don't know what `push` is - we'll cover that [soon](git-mechanics.qmd#core-commands).
## Linking Git to GitHub
Now you have a GitHub account, you need link it to your local Git installation.
There are a couple of different methods for doing this.
The first is to use HTTPS and **Personal Access Tokens (PATs)**.
This is somewhat easier to set up, but it's a little less secure and ultimately is more annoying to use as it often requires entering your username and password each time you connect to GitHub.
The second is to use **SSH**, which is a little more complicated to set up, but is more secure and easier to use once it's set up.
Unlike Jenny Bryan, I think it's worth the effort to set up SSH as you front load the work (though it's not too bad), and then you can just forget about it.
Knowing SSH basics is also really useful as it's the basis for many other things, such as connecting to remote servers and computing on clusters, so will serve you well moving forward.
Instead of trying to cover all eventualities for all operating systems, please work through the excellent GitHub docs on [**PATs**](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and [**SSH**](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
If you are having issues after working through the steps, then try reading [Jenny Bryan's excellent Git guide](https://happygitwithr.com), which covers both [**PATs**](https://happygitwithr.com/https-pat.html#https-pat) and [**SSH**](https://happygitwithr.com/ssh-keys.html#ssh-keys).
If nothing here works, let me know and I'll try to help!
::: {.callout-tip}
If you use the GitKraken client ([detailed here](git-client.qmd#connecting-gitkraken-with-github)), you can use the instructions in their documentation to create and pass the SSH keys directly to GitHub. This assumes you have linked GitKraken to your GitHub account.
:::
That being said, here's an outline of the steps you'll need to take to set up SSH (that are lightly edited from the GitHub documentation).
If on Mac/Linux, this will be in the terminal, and if on Windows, this will be in Git Bash.
1. Create a new SSH key
```bash
# -t specifies the type of cryptography the key will use (ed25519 is more secure than the default RSA generated and recommended by GitHub)
# -f specifies the file name to save the key to
# -C specifies the comment to add to the key i.e., your GitHub email address
ssh-keygen -t ed25519 -f ~/.ssh/github -C "[email protected]"
```
::: {.callout-note}
If you're on MacOS, edit the ***~/.ssh/config*** file using the `open/vi/nano` commands e.g., `open ~/.ssh/config` to add the following lines:
```markdown
Host github.com
AddKeysToAgent yes
UseKeychain yes # delete if you're not using a password for the SSH key
IdentityFile ~/.ssh/github
```
If the file doesn't exist, you can create it using `touch ~/.ssh/config`.
:::
2. Start the SSH agent:
```bash
eval "$(ssh-agent -s)"
```
3. Add the SSH key to the SSH agent:
```bash
## --apple-use-keychain tells the agent to use the macOS keychain to store the passphrase for the key
# Omit if you're not using a password for the SSH key, or if you're using Windows/Linux
ssh-add --apple-use-keychain ~/.ssh/github
```
4. Copy the *public* key contents to your clipboard:
```bash
# print contents to terminal to manually copy
cat ~/.ssh/github.pub
```
5. Navigate to the *Settings > SSH and GPG Keys* section of your GitHub account and click the *New SSH key* button.
Paste in the contents of the *public* key you copied earlier, and click save.
::: {.callout-note}
It would be useful to add GitHub's public key fingerprints to your ***known_hosts*** file, so that you don't get a warning when you connect to GitHub.
You can find the fingerprints [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/githubs-ssh-key-fingerprints).
Currently, you should edit the ***~/.ssh/known_hosts*** file to add the following lines:
```markdown
github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=
github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=
```
:::
6. Test you can connect to GitHub using SSH:
```bash
ssh -T [email protected]
```
::: {.callout-note}
If you're on Windows, you will need to start the `ssh-agent` service before you can use SSH i.e., when you want to use GitHub.
This can be done by running `eval$(ssh-agent -s)` in Git Bash.
However, you can automate this every time you open Git Bash by adding the following line to your ***~/.bashrc*** file:
```bash
env=~/.ssh/agent.env
agent_load_env () { test -f "$env" && . "$env" >| /dev/null ; }
agent_start () {
(umask 077; ssh-agent >| "$env")
. "$env" >| /dev/null ; }
agent_load_env
# agent_run_state: 0=agent running w/ key; 1=agent w/o key; 2=agent not running
agent_run_state=$(ssh-add -l >| /dev/null 2>&1; echo $?)
if [ ! "$SSH_AUTH_SOCK" ] || [ $agent_run_state = 2 ]; then
agent_start
ssh-add
elif [ "$SSH_AUTH_SOCK" ] && [ $agent_run_state = 1 ]; then
ssh-add
fi
unset env
```
:::