@@ -27,6 +27,49 @@ There are two main methods of authentication: through SSH ([Secure Shell](https:
### Authentication method n°1: SSH keys
1) First, you have to create a new pair of SSH keys. You could use an existing pair, but creating a new pair for GitLab is more secure. On your lab machine (e.g., climato\.be) or cluster, go to `~/.ssh` and enter the following command, where `[Comment]` is any information that may help identify the new pair of SSH keys (e.g., _MAR GitLab_). For a different encryption type, refer to [GitLab documentation](https://docs.gitlab.com/user/ssh/).
```
ssh-keygen -t rsa -b 2048 -C "[Comment]"
```
2) Give a suitable name to the new SSH keys, such as ``id_rsa.gitlab``. If you give a name without a path, the new keys will be saved in the local directory, thus `~/.ssh` if you followed step 1.
3) The terminal will ask you to set a passphrase. For convenience, just press Enter twice (with no other input) to not have to use a passphrase when connecting to GitLab.
4) While keeping your terminal open, open your favorite Web browser and log in to https://gitlab.uliege.be.
5) Click on your profile icon (round with a coloured pattern) in the left-hand column, at the top right, to bring up a menu. Go to **Preferences**.
6) In the new _User settings_ menu on the left, click on **SSH keys**.
7) At the top right of the table (empty at first), click on **Add new key**.
8) You now have to copy your new public key into the large text field. You can do so manually, by copy/pasting the content of your public key file (``id_rsa.gitlab.pub`` if you chose ``id_rsa.gitlab`` as a name for you new SSH keys). Under a Linux system (such as on climato\.be), you may copy the public key with the next command before pasting in the GitLab Web interface.
```
xclip -sel clip < ~/.ssh/id_rsa.gitlab.pub
```
9) Give a title to your new key. A good convention may be ``username@device`` (e.g., ``jfgrailet@climato.be``). Do not change the default choice of _Usage type_ (which should be _Authenticating & Signing_).
10) To be able to use your SSH keys indefinitely, click on the white cross on a black background in the _Expiration date_ field (otherwise, enter a suitable date). Finish by clicking on **Add key**.
11) Run the following command to check you can now log in to GitLab through SSH without entering a password, assuming your private key is found at ``~/.ssh/id_rsa.gitlab``. In case of success, you should see a message _Welcome to GitLab, @User!_ in the terminal.
12) In your home folder, use the next command to modify your global ``git`` configuration to customize the prefix of SSH commands used by ``git`` (and for any repository), so that they always use your new private key (in this case, `~/.ssh/id_rsa.gitlab`).
13) Finally, if you previously pulled content from a ESPECES/MAR repository by following the [Getting the latest MAR version (code only)](mar-pull) tutorial, go to the location(s) where you did the pull operation(s) and modify the `.git/config` file (with vim or gedit) to update the `url` field. Indeed, in the previous tutorial, remote repositories were accessed through HTTP. Now, you can (and should) access them through SSH. It simply consists of replacing the ``https://`` prefix by ``git@`` and the forward slash in ``uliege.be/especes`` by a colon (``uliege.be:especes``). E.g., for the [ESPECES/MAR/stable repository](https://gitlab.uliege.be/especes/mar/stable), you should have the following lines in your `.git/config`.
```
[remote "origin"]
url = git@gitlab.uliege.be:especes/mar/stable.git
fetch = +refs/heads/*:refs/remotes/origin/*
```
### Authentication method n°2: Personal Access Token (PAT)
1) Log in to https://gitlab.uliege.be.
...
...
@@ -41,7 +84,7 @@ There are two main methods of authentication: through SSH ([Secure Shell](https:
6) On the new page, in the green box, click on the eye icon (or better still, the copy/paste icon next to it). Copy the sequence into your clipboard or a text file in a secure but temporary location (e.g. on your personal computer).
7) Now, from any location on your lab machine (e.g., climato\.be) or cluster, run the following commands to add your GitLab username and associated email address. The keyword ``--global`` ensures that this information can be used for all repositories.
7) Now, from your home directory on your lab machine (e.g., climato\.be) or cluster, run the following commands to add your GitLab username and associated email address. The keyword ``--global`` ensures that this information can be used for all repositories.
All of the following commands are to be executed from the directory where you copied a ESPECES/MAR repository (if you followed [the previous tutorial](mar-pull), such folder may be `~/GitLab/MAR/stable`), assuming that you have followed all steps from the previous sections. For this tutorial, we will assume you want to modify MAR source code and push them to [ESPECES/MAR/stable](https://gitlab.uliege.be/especes/mar/stable).
All of the following commands are to be executed from the directory where you copied a ESPECES/MAR repository (if you followed [the previous tutorial](mar-pull), this folder may be `~/GitLab/MAR/stable`), assuming that you have followed all steps from the previous sections. For this tutorial, we will assume you want to modify MAR source code and push your changes to [ESPECES/MAR/stable](https://gitlab.uliege.be/especes/mar/stable).
1) Use the ``git add path/to/changes`` command to add the files that have been modified for the next _commit_. There is no need to do this file by file or to restrict yourself to modified files: you can specify a folder path or a pattern, for example to the modified MAR source code (even if you have only changed a single file), as shown below. ``git`` will then detect the modified files by itself.
