From f3e921d7ff49b2fdc7749fbf52e6efd4f6133b24 Mon Sep 17 00:00:00 2001 From: JoschD <26184899+JoschD@users.noreply.github.com> Date: Fri, 26 Sep 2025 14:31:08 +0200 Subject: [PATCH 1/5] added quickstart --- docs/resources/git_setup.md | 116 ++++++++++++++++++++++++++++++++++-- 1 file changed, 111 insertions(+), 5 deletions(-) diff --git a/docs/resources/git_setup.md b/docs/resources/git_setup.md index f691dfc9..14cefc59 100644 --- a/docs/resources/git_setup.md +++ b/docs/resources/git_setup.md @@ -2,6 +2,113 @@ 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 a few years, github has disabled access via password only for security reasons, +so you need to cre +This aims to be as short and concise as possible, for more extenive information, [see the github security documentation][github_security]. + +## Setup SSH Access + +An easy way to access github securely is to use SSH. + +### Create SSH Key + +For this, you first need to create a SSH key pair on your computer using the email address of your github account. + +```bash +ssh-keygen -t ed25519 -C "your_email@example.com" +``` + +When asked for a location, it make sense to give it an easily identifiable name, so you will know 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_sshkey +``` + +This will create two files: `github_sshkey` and `github_sshkey.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 SSH Key to Github + +After creating the key, you need to add it to your github account. +For this you need to 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 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/config` file: + +```bash +Host github.com + HostName github.com + User git + IdentityFile ~/.ssh/github_sshkey +``` + +or the path to your key you chose earlier. + +!!! 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 I am using SSH access, this is not yet documented. + 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 If you are programming locally, but also want to have a copy on AFS, either because your colleges are not comfortable with Gitlab or you need the code for other scripts that you are running on lxplus or similar, here is how: @@ -120,12 +227,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 From 1726ee495d9035bdd6d5a1c24ea69c4ecff5a00a Mon Sep 17 00:00:00 2001 From: JoschD <26184899+JoschD@users.noreply.github.com> Date: Fri, 26 Sep 2025 14:34:36 +0200 Subject: [PATCH 2/5] wrong title levels --- docs/resources/git_setup.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/resources/git_setup.md b/docs/resources/git_setup.md index 14cefc59..ec4ae273 100644 --- a/docs/resources/git_setup.md +++ b/docs/resources/git_setup.md @@ -9,11 +9,11 @@ Since a few years, github has disabled access via password only for security rea so you need to cre This aims to be as short and concise as possible, for more extenive information, [see the github security documentation][github_security]. -## Setup SSH Access +### Setup SSH Access An easy way to access github securely is to use SSH. -### Create SSH Key +#### Create SSH Key For this, you first need to create a SSH key pair on your computer using the email address of your github account. @@ -35,7 +35,7 @@ while the other file is your private key and **should never be shared with anyon !!! quote "Keep it secret, keep it safe!" _Gandalf_, about private SSH keys (probably). -### Add SSH Key to Github +#### Add SSH Key to Github After creating the key, you need to add it to your github account. For this you need to log into your github account, click on your avatar and go to `Settings` → `SSH and GPG keys`. @@ -44,7 +44,7 @@ Then click on [++"New SSH key"++{.green-gui-button}][github_new_ssh_key]{target= Give it a resonable name in the `Title` field and leave the `Key type` as `Authentication key`. Then click on `Add SSH key` and you are done. -### Configure SSH to use the key +#### 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/config` file: @@ -62,7 +62,7 @@ or the path to your key you chose earlier. 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 +#### Test Access Now you can test that everything works by running the following command: @@ -76,7 +76,7 @@ which should then display Hi ! You've successfully authenticated, but GitHub does not provide shell access. ``` -### Clone Repository +#### Clone Repository When you clone a new repository, always use the SSH url @@ -100,7 +100,7 @@ which you can find from the ++"Clone"++{.green-gui-button} button of the reposit git remote -v ``` -## Setup HTTPS Access +### Setup HTTPS Access You can setup https access by creating and using a personal access token or a password manager. From 9017ea379ee503012619398728a950c8fc3a5537 Mon Sep 17 00:00:00 2001 From: JoschD <26184899+JoschD@users.noreply.github.com> Date: Fri, 26 Sep 2025 14:35:54 +0200 Subject: [PATCH 3/5] renamed key --- docs/resources/git_setup.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/resources/git_setup.md b/docs/resources/git_setup.md index ec4ae273..cdc165dd 100644 --- a/docs/resources/git_setup.md +++ b/docs/resources/git_setup.md @@ -25,10 +25,10 @@ When asked for a location, it make sense to give it an easily identifiable name, The file should be placed in `~/.ssh/`, unless you are on `afs`, in which case the `~/private/` directory should be used. ```text -~/.ssh/github_sshkey +~/.ssh/github_authenticate ``` -This will create two files: `github_sshkey` and `github_sshkey.pub`. +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!** @@ -53,7 +53,7 @@ For that, add the following lines to your `~/.ssh/config` file: Host github.com HostName github.com User git - IdentityFile ~/.ssh/github_sshkey + IdentityFile ~/.ssh/github_authenticate ``` or the path to your key you chose earlier. From 3dd82c0fb5e3b326084ce85490965eafe8a0bdef Mon Sep 17 00:00:00 2001 From: JoschD <26184899+JoschD@users.noreply.github.com> Date: Fri, 26 Sep 2025 14:40:11 +0200 Subject: [PATCH 4/5] passphrase --- docs/resources/git_setup.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/resources/git_setup.md b/docs/resources/git_setup.md index cdc165dd..8632813e 100644 --- a/docs/resources/git_setup.md +++ b/docs/resources/git_setup.md @@ -28,6 +28,12 @@ The file should be placed in `~/.ssh/`, unless you are on `afs`, in which case t ~/.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 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!** From 2b30452b7f724831c29015b4731c582839855ed1 Mon Sep 17 00:00:00 2001 From: JoschD <26184899+JoschD@users.noreply.github.com> Date: Fri, 26 Sep 2025 15:07:11 +0200 Subject: [PATCH 5/5] felix suggestions and one more sentence linking to the ssh github page --- docs/resources/git_setup.md | 41 +++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/docs/resources/git_setup.md b/docs/resources/git_setup.md index 8632813e..bac93064 100644 --- a/docs/resources/git_setup.md +++ b/docs/resources/git_setup.md @@ -1,27 +1,28 @@ # 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 a few years, github has disabled access via password only for security reasons, -so you need to cre -This aims to be as short and concise as possible, for more extenive information, [see the github security documentation][github_security]. +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. +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, you first need to create a SSH key pair on your computer using the email address of your github account. +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 make sense to give it an easily identifiable name, so you will know what the key is for. +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 @@ -32,7 +33,7 @@ The file should be placed in `~/.ssh/`, unless you are on `afs`, in which case t 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 recommended, to use a passphrase** but as it is just an extra layer of security, you can keep it short and simple. + **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, @@ -41,19 +42,19 @@ while the other file is your private key and **should never be shared with anyon !!! quote "Keep it secret, keep it safe!" _Gandalf_, about private SSH keys (probably). -#### Add SSH Key to Github +#### Add the Public SSH Key to GitHub -After creating the key, you need to add it to your github account. -For this you need to log into your github account, click on your avatar and go to `Settings` → `SSH and GPG keys`. +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 and leave the `Key type` as `Authentication key`. +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/config` file: +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 @@ -62,11 +63,11 @@ Host github.com IdentityFile ~/.ssh/github_authenticate ``` -or the path to your key you chose earlier. +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. + GitHub will identify you automatically based on the email address you used to create the SSH key. #### Test Access @@ -90,7 +91,7 @@ When you clone a new repository, always use the SSH url 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. +which you can find from the ++"Clone"++{.green-gui-button} button of the repository page on GitHub. !!! tip "Changing a Repository URL" @@ -111,8 +112,8 @@ which you can find from the ++"Clone"++{.green-gui-button} button of the reposit You can setup https access by creating and using a personal access token or a password manager. !!! note "Not yet documented" - As I am using SSH access, this is not yet documented. - Refer to the [github documentation][github_https] for more information and maybe write up a quick howto. + 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