diff --git a/docs/resources/git_setup.md b/docs/resources/git_setup.md index f691dfc9..bac93064 100644 --- a/docs/resources/git_setup.md +++ b/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 "your_email@example.com" +``` + +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 ! 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 git@github.com: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 git@github.com: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 \ No newline at end of file