diff --git a/doc/gitlab-basics/README.md b/doc/gitlab-basics/README.md index 493e1d1b09c1b5a1fe0e188343630b4d705f028a..b5214a4c38fe2e588b2de0886b90c4fbae86bfea 100644 --- a/doc/gitlab-basics/README.md +++ b/doc/gitlab-basics/README.md @@ -1,27 +1,210 @@ -# GitLab basics +# GitLab Basics -Step-by-step guides on the basics of working with Git and GitLab. +[Create an Account](#create-an-account) -* [Start using Git on the command line](start-using-git.md) +[Install and Configure Git](#install-and-configure-git) -* [Create and add your SSH Keys](create-your-ssh-keys.md) +[Add an SSH Key Pair](#add-an-ssh-key-pair) -* [Command Line basic commands](command-line-commands.md) +[Create a Project](#create-a-project) -* [Basic Git commands](basic-git-commands.md) +## Create an Account -* [Create a project](create-project.md) +Before you can start using GitLab you need a user account. GitLab offers several +ways to create an account or sign in, depending on how your GitLab instance is +configured. -* [Create a group](create-group.md) +### Create a GitLab account -* [Create a branch](create-branch.md) +Create an account on GitLab by visiting the GitLab sign in page. For example, +http://gitlab.com/users/sign_in -* [Fork a project](fork-project.md) +Fill in the information in the 'New user? Create an account' box. -* [Add a file](add-file.md) +![New User Sign Up](images/create-an-account/new_user_sign_up.png) -* [Add an image](add-image.md) +Check your email to find the confirmation email. Click on the link in the email. -* [Create a Merge Request](add-merge-request.md) +![Confirmation Email](images/create-an-account/confirmation_email.png) + +If confirmation is successful, you should be signed in. + +### Third-party sign in + +Look for third-party icons on the sign in page to determine if your GitLab +instance supports third-party sign ins. Examples include Google, Twitter, +Github and BitBucket. For example, GitLab.com sign in page looks like the following. + +![Third-party Sign In](images/create-an-account/sign_in.png) + +Click on any one of these icons to use your third-party account with GitLab. +You will be redirected to the third-party service to sign in and authorize +GitLab. After successful authentication and authorization you will be redirected +to GitLab and signed in. + +## Install and Configure Git + +To interact with GitLab projects you will need to install the Git command +line utility. This utility allows you to clone projects, push and pull code, and +stay in sync with the central repository. + +### Command Line Interface + +Use a command line interface (also called a terminal or shell) to run the commands +on the right. Depending on your operating system, find the application of your preference. +Here are some suggestions. + +- [Terminal](http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line) on Mac OSX +- [GitBash](https://msysgit.github.io) on Windows +- [Linux Terminal](http://www.howtogeek.com/140679/beginner-geek-how-to-start-using-the-linux-terminal/) on Linux + +It is important to configure Git with your username and +email address. Git and GitLab use this information to identify your changes. + +Check if Git is already installed + +```shell +git --version + +# If Git is installed the output will be similar to: +git version 2.3.8 + +# If Git is not installed the output will be similar to: +-bash: git: command not found +``` + +Add your Git username and set your email + +```bash +git config --global user.name "Your Name" +git config --global user.email you@example.com +``` + +Verify your configuration information + +```bash +git config --global --list + +# Result: +user.name=Your Name +user.email=you@example.com +``` + +## Add an SSH Key Pair + +SSH keys allow you to interact with GitLab using the Git command line +tool. Instead of using your username and password, the SSH key will securely +authenticate you. You will need to complete these steps on each computer +you want to use with GitLab. + +### Generate an SSH key pair + +Before you can add your public key to your GitLab account you need to check if +you have an SSH key pair. If not, you need to generate one. + +It is a best practice to enter a passphrase (password) when +generating an SSH key, but it is not required. You can skip creating a password +by pressing enter (using an empty password). Note that the password you choose +here can't be altered without generating a new key pair. You will only need to +provide this password the first time you use Git or SSH after logging in +to your computer. You will not be asked every time you push, pull, or clone. + +Check if you already have an SSH key + +```bash +cat ~/.ssh/id_rsa.pub + +# If you already have a key it will look something like this +ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAEAQDVvUplNVHBJLyezQ/hq4yzETyXiwkgHZbet9q8ftp+TcputKd7V1NCOuHGjfIPWF1 you@computer-name + +# If you do not have a key you will see an error like this +cat: /Users/you/.ssh/id_rsa.pub: No such file or directory +``` + +Generate a new SSH key pair if you received an error above + +```bash +ssh-keygen -t rsa -b 4096 -C "you@computer-name" + +# You will be prompted for the following information. Press enter to accept the defaults. Defaults appear in parentheses. +Generating public/private rsa key pair. +Enter file in which to save the key (/Users/you/.ssh/id_rsa): +Enter passphrase (empty for no passphrase): +Enter same passphrase again: +Your identification has been saved in /Users/you/.ssh/id_rsa. +Your public key has been saved in /Users/you/.ssh/id_rsa.pub. +The key fingerprint is: +39:fc:ce:94:f4:09:13:95:64:9a:65:c1:de:05:4d:01 you@computer-name +``` + +### Add your SSH Key to your GitLab account + + +First, copy the contents of your SSH public key. Then, from the GitLab Dashboard +click on "Profile Settings" + +![Profile Settings](images/profile_settings_menu.png) + +Copy the contents of your SSH public key + +```bash +cat ~/.ssh/id_rsa.pub +``` + +Copy everything including the `ssh-rsa` and `you@computer-name` portion + +```bash +# Example public key as output by the previous command +ssh-rsa AAAAB3NzaC1yc2EAAAADAQEL17Ufacg8cDhlQMS5NhV8z3GHZdhCrZbl4gz you@example.com +``` + +Click "SSH Keys": + +![SSH Keys](images/ssh_keys_profile_menu.png) + +Click on the "Add SSH Key" button + +![Add SSH Key](images/add_ssh_key_button.png) + +Paste your SSH public key in the "Key" text area. The title will be added automatically. +Click "Add key" to save your public key. + +![Paste SSH Key](images/add_ssh_key.png) + +Now, you'll be able to use Git over SSH. + +## Create a Project + +Create your first project to start using GitLab. If this is your first project +you will see the welcome message on the dashboard. Click 'New Project'. + +![New Project Welcome](images/welcome_new_project.png) + +Enter the project details and click 'Create project'. + +- The 'Project path' serves as both the project name +and the URL. +- The 'Description' is optional and is any text you wish to provide +to describe your new project. +- The 'Visibility Level' is very important. Set this correctly to determine +who has access to your project. + +GitLab also supports importing existing projects from third-party repositories. +Depending on how your GitLab instance is configured, some options may be greyed +out. Ask your administrator to configure these integrations if you want +to use one that is greyed out. + +![New Project Page](images/new_project_page.png) + +## Basic Git Commands + +(inc. basic CLI commands) + +## Other topics + +### Create a Merge Request + +### Group management + +### Fork a project (This is not 'basic') -* [Create an Issue](create-issue.md) diff --git a/doc/gitlab-basics/images/add_ssh_key.png b/doc/gitlab-basics/images/add_ssh_key.png new file mode 100644 index 0000000000000000000000000000000000000000..2cc4acea2b8b69e7cd262b55b578a5ddeb29ec56 Binary files /dev/null and b/doc/gitlab-basics/images/add_ssh_key.png differ diff --git a/doc/gitlab-basics/images/add_ssh_key_button.png b/doc/gitlab-basics/images/add_ssh_key_button.png new file mode 100644 index 0000000000000000000000000000000000000000..dc94fa15747336042e18d4ce01c213b9a3b67c61 Binary files /dev/null and b/doc/gitlab-basics/images/add_ssh_key_button.png differ diff --git a/doc/gitlab-basics/images/create-an-account/confirmation_email.png b/doc/gitlab-basics/images/create-an-account/confirmation_email.png new file mode 100644 index 0000000000000000000000000000000000000000..d661ac3969aa43f4478d7aeda374c506cb130ca7 Binary files /dev/null and b/doc/gitlab-basics/images/create-an-account/confirmation_email.png differ diff --git a/doc/gitlab-basics/images/create-an-account/new_user_sign_up.png b/doc/gitlab-basics/images/create-an-account/new_user_sign_up.png new file mode 100644 index 0000000000000000000000000000000000000000..9154cde7599106dea6b5e33a7dee7b9c05b53893 Binary files /dev/null and b/doc/gitlab-basics/images/create-an-account/new_user_sign_up.png differ diff --git a/doc/gitlab-basics/images/create-an-account/sign_in.png b/doc/gitlab-basics/images/create-an-account/sign_in.png new file mode 100644 index 0000000000000000000000000000000000000000..c3aceda9e2215c25cd41245185c1d42581ec418b Binary files /dev/null and b/doc/gitlab-basics/images/create-an-account/sign_in.png differ diff --git a/doc/gitlab-basics/images/new_project_page.png b/doc/gitlab-basics/images/new_project_page.png new file mode 100644 index 0000000000000000000000000000000000000000..87c2545f920d1184d6e524a7eccbd0b81b43cf83 Binary files /dev/null and b/doc/gitlab-basics/images/new_project_page.png differ diff --git a/doc/gitlab-basics/images/profile_settings.png b/doc/gitlab-basics/images/profile_settings.png new file mode 100644 index 0000000000000000000000000000000000000000..5f2e7a7e10cd762c7f373155714fb2c8264b37a4 Binary files /dev/null and b/doc/gitlab-basics/images/profile_settings.png differ diff --git a/doc/gitlab-basics/images/profile_settings_menu.png b/doc/gitlab-basics/images/profile_settings_menu.png new file mode 100644 index 0000000000000000000000000000000000000000..8b56d04ed6d7b4e6f0fa4eff033a215ef6d6cbc3 Binary files /dev/null and b/doc/gitlab-basics/images/profile_settings_menu.png differ diff --git a/doc/gitlab-basics/images/ssh_keys_profile_menu.png b/doc/gitlab-basics/images/ssh_keys_profile_menu.png new file mode 100644 index 0000000000000000000000000000000000000000..bccee4598d02cd631ddc0e81fcf7889d2115ae47 Binary files /dev/null and b/doc/gitlab-basics/images/ssh_keys_profile_menu.png differ diff --git a/doc/gitlab-basics/images/welcome_new_project.png b/doc/gitlab-basics/images/welcome_new_project.png new file mode 100644 index 0000000000000000000000000000000000000000..0272cdd7864ff5635fb816a91e645138e9467aa6 Binary files /dev/null and b/doc/gitlab-basics/images/welcome_new_project.png differ