Quickstart for github setup

docs/resources/git_setup.md

@@ -1,6 +1,120 @@
 # Git
 
-How to's concerning  `git` in general,  [`gitlab`][cern_gitlab], [`github`][github] and CI.
+How to's concerning  `git` in general,  [`gitlab`][cern_gitlab], [`GitHub`][github] and CI.
+
+## Github Commandline Access Quickstart
+
+This section explains the basic steps to get started with GitHub.
+Since HTTP access via password only has been disabled by GitHub for security reasons, it is necessary to activate a secure method.
+
+This aims to be as short and concise as possible, for more extensive information, [see the GitHub security documentation][github_security]{target=_blank}.
+
+### Setup SSH Access
+
+An easy way to access GitHub securely is to use SSH.
+This guides you through the basic steps, but [details can be found in the GitHub documentation][github_ssh].
+
+#### Create SSH Key
+
+For this, create an SSH key pair locally using the email address associated with your GitHub account:
+
+```bash
+ssh-keygen -t ed25519 -C "[email protected]"
+```
+
+When asked for a location, it makes sense to give it an easily identifiable name, to remember what the key is for.
+The file should be placed in `~/.ssh/`, unless you are on `afs`, in which case the `~/private/` directory should be used.
+
+```text
+~/.ssh/github_authenticate
+```
+
+!!! tip "Passphrase"
+    You can optionally provide a passphrase for the key, which will make it more secure.
+    This way, even if someone else gets a hold of the private key file, they will not be able to access it.
+    On the downside, you will be asked to enter the passphrase every time you want to use the key.
+    **It is recommended, to use a passphrase** but as it is just an extra layer of security, you can keep it short and simple.
+
+This will create two files: `github_authenticate` and `github_authenticate.pub`.
+The `.pub` is your public key that you can share with others,
+while the other file is your private key and **should never be shared with anyone!**
+
+!!! quote "Keep it secret, keep it safe!"
+    _Gandalf_, about private SSH keys (probably).
+
+#### Add the Public SSH Key to GitHub
+
+After creating the key, you need to add it to your GitHub account.
+Log into your GitHub account, click on your avatar and go to `Settings` → `SSH and GPG keys`.
+Then click on [++"New SSH key"++{.green-gui-button}][github_new_ssh_key]{target=_blank} and paste the contents of the `.pub` file into the `Key` field.
+
+Give it a resonable name in the `Title` field (which it will appear as in the GitHub interface) and leave the `Key type` as `Authentication key`.
+Then click on `Add SSH key` and you are done.
+
+#### Configure SSH to use the key
+
+Next, you need to tell your local SSH client to use the key you created to connect to GitHub.
+For that, add the following lines to your `ssh` configuration file (typically at `~/.ssh/config` on UNIX systems):
+
+```bash
+Host github.com
+  HostName github.com
+  User git
+  IdentityFile ~/.ssh/github_authenticate
+```
+
+or use for the `IdentityFile` field the path you chose earlier for the ssh key file.
+
+!!! warning "Username"
+    It is important that the `User` is `git` and **not your git-username**!
+    GitHub will identify you automatically based on the email address you used to create the SSH key.
+
+#### Test Access
+
+Now you can test that everything works by running the following command:
+
+```bash
+ssh -T github.com
+```
+
+which should then display
+
+```text
+Hi <Username>! You've successfully authenticated, but GitHub does not provide shell access.
+```
+
+#### Clone Repository
+
+When you clone a new repository, always use the SSH url
+
+```text
+git clone [email protected]:pylhc/omc3.git
+```
+
+which you can find from the ++"Clone"++{.green-gui-button} button of the repository page on GitHub.
+
+
+!!! tip "Changing a Repository URL"
+    In case you already have a repository cloned with the wrong URL, you can change it with `git remote set-url`, e.g.:
+
+    ```bash
+    git remote set-url origin [email protected]:pylhc/omc3.git
+    ```
+
+    If you are not sure which url is currently set, you can always check it with
+
+    ```bash
+    git remote -v
+    ```
+
+### Setup HTTPS Access
+
+You can setup https access by creating and using a personal access token or a password manager.
+
+!!! note "Not yet documented"
+    As we use SSH access, this section not yet written.
+    Refer to the [GitHub documentation][github_https] for more information and maybe write up a quick howto.
+
 
 ## Configuring Gitlab CI to Automatically Pull into AFS
 
@@ -120,12 +234,11 @@ Whenever you are pushing now any commits to the `master` branch, the CI/CD will
 *[CD]: Continuous Delivery
 *[lxplus]: Linux Public Login User Service
 
-[sshuttle]: https://sshuttle.readthedocs.io/en/stable/
 [new_account]: https://account.cern.ch/account/Management/NewAccount.aspx
 [afs_services]: https://resources.web.cern.ch/resources/Manage/AFS/Default.aspx
 [github]: https://github.com/
 [cern_gitlab]: https://gitlab.cern.ch/
-[cern_linux]: https://linux.web.cern.ch/dockerimages/
-[acc_models_repo]: https://gitlab.cern.ch/acc-models/acc-models-lhc/
-[acc_models_yml]: https://gitlab.cern.ch/acc-models/acc-models-lhc/-/blob/2018/.gitlab-ci.yml
-[acc_models_docker]: https://gitlab.cern.ch/acc-models/acc-models-www/-/blob/master/_docker/Dockerfile_cern_cc7_base
+[github_security]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure
+[github_https]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github#https
+[github_ssh]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh
+[github_new_ssh_key]: https://github.com/settings/ssh/new