From 564c37d9b69367fb7384a22edad53c8e75aeb2cb Mon Sep 17 00:00:00 2001 From: Jeroen van Baarsen Date: Thu, 13 Feb 2014 11:55:46 +0100 Subject: Moved all the help files to markdown files: Files moved: * Workflow * help/ssh * help/webhooks * help/system_hooks * help/public_access * help/permissions --- doc/permissions/permissions.md | 45 +++++++++++++++ doc/public_access/public_access.md | 28 +++++++++ doc/ssh/ssh.md | 24 ++++++++ doc/system_hooks/system_hooks.md | 89 +++++++++++++++++++++++++++++ doc/web_hooks/web_hooks.md | 113 +++++++++++++++++++++++++++++++++++++ doc/workflow/workflow.md | 26 +++++++++ 6 files changed, 325 insertions(+) create mode 100644 doc/permissions/permissions.md create mode 100644 doc/public_access/public_access.md create mode 100644 doc/ssh/ssh.md create mode 100644 doc/system_hooks/system_hooks.md create mode 100644 doc/web_hooks/web_hooks.md create mode 100644 doc/workflow/workflow.md (limited to 'doc') diff --git a/doc/permissions/permissions.md b/doc/permissions/permissions.md new file mode 100644 index 00000000000..73e1728a559 --- /dev/null +++ b/doc/permissions/permissions.md @@ -0,0 +1,45 @@ +Users have different abilities depending on the access level they have in a particular group or project. +If a user is both in a project group and in the project itself, the highest permission level is used. +If a user is a GitLab administrator they receive all permissions. + +--- + +#### Project: + + +| Action| Guest | Reporter | Developer | Master | Owner| +|-------|-------|----------|-----------|--------|------| +|Create new issue|✓|✓|✓|✓|✓| +|Leave comments|✓|✓|✓|✓|✓| +|Write on project wall|✓|✓|✓|✓|✓| +|Pull project code| |✓|✓|✓|✓| +|Download project| |✓|✓|✓|✓| +|Create code snippets| |✓|✓|✓|✓| +|Create new merge request| ||✓|✓|✓| +|Create new branches| ||✓|✓|✓| +|Push to non-protected branches| ||✓|✓|✓| +|Remove non-protected branches| ||✓|✓|✓| +|Add tags| ||✓|✓|✓| +|Write a wiki| ||✓|✓|✓| +|Manage issue tracker| ||✓|✓|✓| +|Add new team members| |||✓|✓| +|Push to protected branches| |||✓|✓| +|Remove protected branches| |||✓|✓| +|Edit project| |||✓|✓| +|Add Deploy Keys to project| |||✓|✓| +|Confiure Project Hooks| |||✓|✓| +|Switch visibility level| ||||✓| +|Transfer project to another namespace| ||||✓| +|Remove project| ||||✓| + +#### Group + +|Action|Guest|Reporter|Developer|Master|Owner| +|------|-----|--------|---------|------|-----| +|Browse group|✓|✓|✓|✓|✓| +|Edit group|||||✓| +|create project in group|||||✓| +|Manage group members|||||✓| +|Remove group|||||✓| + +Any user can remove himself from a group, unless he is the last Owner of the group. diff --git a/doc/public_access/public_access.md b/doc/public_access/public_access.md new file mode 100644 index 00000000000..bf9d2784aff --- /dev/null +++ b/doc/public_access/public_access.md @@ -0,0 +1,28 @@ +Gitlab allows you to open selected projects to be accessed **publicly** or **internally**. +Projects with either of these visibility levels will be listen in the [public access directory](/public). +Internal projects will only be available to authenticated users. + +#### Public projects +Public projects can be cloned **without any** authentication. +It will also be listen on the [public access directory](/public). +**Any logged in user** will have [Guest](/help/permissions) permissions on the repository. + +#### Internal projects +Internal projects can be cloned by any logged in user. +It will also be listed on the [public access directory](/public) for logged in users. +Any logged in user will have [Guest](/help/permissions) permissions on the repository. + +#### How to change project visibility +1. Go to your project dashboard +2. Click on the "Edit" tab +3. Change "Visibility Level" + +#### Visibility of users +The public page of users, located at `/u/username` is visible if either: + +* You are logged in. +* You are logged out, and the target user is authorized to (is Guest, Reporter, etc.) at least one public project. + +Otherwise, you will be redirected to the sign in page. + +When visiting the public page of an user, you will only see listed projects which you can view yourself. diff --git a/doc/ssh/ssh.md b/doc/ssh/ssh.md new file mode 100644 index 00000000000..0a38bc16b49 --- /dev/null +++ b/doc/ssh/ssh.md @@ -0,0 +1,24 @@ +SSH key allows you to establish a secure connection between your computer and GitLab + + +Before generating an SSH key, check if your system already has one by running `cat ~/.ssh/id_rsa.pub` +If your see a long string starting with `ssh-rsa` or `ssh-dsa`, you can skip the ssh-keygen step. + + +To generate a new SSH key just open your terminal and use code below. The ssh-keygen command prompts you for a location and filename to store the key pair and for a password. +When prompted for the location and filename you can press enter to use the default. +It is a best practice to use a password for an SSH key but it is not required and you can skip creating a password by pressing enter. +Note that the password you choose here can't be altered or retrieved. + +```bash +ssh-keygen -t rsa -C "$your_email" +``` + +Use the code below to show your public key. + +```bash +cat ~/.ssh/id_rsa.pub +``` + +Copy-paste the key to the 'My SSH Keys' section under the 'SSH' tab in your user profile. +Please copy the complete key starting with `ssh-` and ending with your username and host. diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md new file mode 100644 index 00000000000..fe32ca1a9fa --- /dev/null +++ b/doc/system_hooks/system_hooks.md @@ -0,0 +1,89 @@ +Your GitLab instance can perform HTTP POST requests on the following events: `create_project`, `delete_project`, `create_user`, `delete_user` and `change_team_member`. + +System hooks can be used, e.g. for logging or changing information in a LDAP server. + +#### Hooks request example: + +**Project created:** + +```json +{ + "created_at": "2012-07-21T07:30:54Z", + "event_name": "project_create", + "name": "StoreCloud", + "owner_email": "johnsmith@gmail.com" + "owner_name": "John Smit", + "path": "stormcloud", + "path_with_namespace": "jsmith/stormcloud", + "project_id": 74, +} +``` + +**Project destroyed:** + +```json +{ + "created_at": "2012-07-21T07:30:58Z", + "event_name": "project_destroy", + "name": "Underscore", + "owner_email": "johnsmith@gmail.com" + "owner_name": "John Smith", + "path": "underscore", + "path_with_namespace": "jsmith/underscore", + "project_id": 73, +} +``` + +**New Team Member:** + +```ruby +{ + "created_at": "2012-07-21T07:30:56Z", + "event_name": "user_add_to_team", + "project_access": "Master", + "project_id": 74, + "project_name": "StoreCloud", + "project_path": "storecloud", + "user_email": "johnsmith@gmail.com", + "user_name": "John Smith", +} +``` + +**Team Member Removed:** + +```json +{ + "created_at": "2012-07-21T07:30:56Z", + "event_name": "user_remove_from_team", + "project_access": "Master", + "project_id": 74, + "project_name": "StoreCloud", + "project_path": "storecloud", + "user_email": "johnsmith@gmail.com", + "user_name": "John Smith", +} +``` + +**User created:** + +```json +{ + "created_at": "2012-07-21T07:44:07Z", + "email": "js@gitlabhq.com", + "event_name": "user_create", + "name": "John Smith", + "user_id": 41 +} +``` + +**User removed:** + +```json +{ + "created_at": "2012-07-21T07:44:07Z", + "email": "js@gitlabhq.com", + "event_name": "user_destroy", + "name": "John Smith", + "user_id": 41 +} +``` diff --git a/doc/web_hooks/web_hooks.md b/doc/web_hooks/web_hooks.md new file mode 100644 index 00000000000..ba8083c3601 --- /dev/null +++ b/doc/web_hooks/web_hooks.md @@ -0,0 +1,113 @@ +Project web hooks allow you to trihher an url if new code is pushed or a new issue is created. + +--- + +You can configure web hook to listen for specific events like pushes, issues, merge requests. +GitLab will send POST request with data to web hook url. +Web Hooks can be used to update an external issue tracker, trigger CI builds, update a backup mirror, or even deploy to your production server. + +--- + +#### Push events +Triggered when you push to the repository except pushing tags. + +**Request body:** + +```json +{ + "before": "95790bf891e76fee5e1747ab589903a6a1f80f22", + "after": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", + "ref": "refs/heads/master", + "user_id": 4, + "user_name": "John Smith", + "project_id": 15, + "repository": { + "name": "Diaspora", + "url": "git@localhost:diaspora.git", + "description": "", + "homepage": "http://localhost/diaspora", + }, + "commits": [ + { + "id": "b6568db1bc1dcd7f8b4d5a946b0b91f9dacd7327", + "message": "Update Catalan translation to e38cb41.", + "timestamp": "2011-12-12T14:27:31+02:00", + "url": "http://localhost/diaspora/commits/b6568db1bc1dcd7f8b4d5a946b0b91f9dacd7327", + "author": { + "name": "Jordi Mallach", + "email": "jordi@softcatala.org", + } + }, + // ... + { + "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", + "message": "fixed readme", + "timestamp": "2012-01-03T23:36:29+02:00", + "url": "http://localhost/diaspora/commits/da1560886d4f094c3e6c9ef40349f7d38b5d27d7", + "author": { + "name": "GitLab dev user", + "email": "gitlabdev@dv6700.(none)", + }, + }, + ], + "total_commits_count": 4, +}; +``` + +#### Issues events + +Triggered when a new issue is created or an existing issue was updated/closed/reopened. + +**Request body:** + +```json +{ + "object_kind":"issue", + "object_attributes":{ + "id":301, + "title":"New API: create/update/delete file", + "assignee_id":51, + "author_id":51, + "project_id":14, + "created_at":"2013-12-03T17:15:43Z", + "updated_at":"2013-12-03T17:15:43Z", + "position":0, + "branch_name":null, + "description":"Create new API for manipulations with repository", + "milestone_id":null, + "state":"opened", + "iid":23 + } +} +``` + +#### Merge request events + +Triggered when a new merge request is created or an existing merge request was updated/merges/closed. + +**Request body:** + +```json +{ + "object_kind":"merge_request", + "object_attributes":{ + "id":99, + "target_branch":"master", + "source_branch":"ms-viewport", + "source_project_id":14, + "author_id":51, + "assignee_id":6, + "title":"MS-Viewport", + "created_at":"2013-12-03T17:23:34Z", + "updated_at":"2013-12-03T17:23:34Z", + "st_commits":null, + "st_diffs":null, + "milestone_id":null, + "state":"opened", + "merge_status":"unchecked", + "target_project_id":14, + "iid":1, + "description":"" + } +} +``` diff --git a/doc/workflow/workflow.md b/doc/workflow/workflow.md new file mode 100644 index 00000000000..1c238f74957 --- /dev/null +++ b/doc/workflow/workflow.md @@ -0,0 +1,26 @@ +1. Clone project + + ```bash + git clone git@example.com:project-name.git + ``` +2. Create branch with your feature + + ```bash + git checkout -b $feature_name + ``` + +3. Write code. Comit changes + + ```bash + git commit -am "My feature is ready" + ``` + +4. Push your branch to GitLab + + ```bash + git push origin $feature_name + ``` + +5. Review your code on Commits page +6. Create a merge request +7. Your team lead will review the code & merge it to the main branch -- cgit v1.2.3