BigW Consortium Gitlab

Skip to content

G
gitlab-ce
Commit a9dcfd85 by Dmitriy Zaporozhets
Options

Merge pull request #6308 from jvanbaarsen/help-to-markdown

Convert all help files to markdown files in doc directory
parents 54e40241 c06f4cd4
Showing with 295 additions and 510 deletions
app/views/help/permissions.html.haml
= render layout: 'help/layout' do
%h3.page-title Permissions
%p.light Users have different abilities depending on the access level they have in particular group or project.
%p.light If a user is both in a project group and in the project itself the highest permission level is used.
%p.light If a user is a GitLab administrator they receive all permissions.
%hr
%h4 Project:
%table.table
%thead
%tr
%th Action
%th Guest
%th Reporter
%th Developer
%th Master
%th Owner
%tbody
%tr
%td Create new issue
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Leave comments
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Write on project wall
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Pull project code
%td
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Download project
%td
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Create code snippets
%td
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Create new merge request
%td
%td
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Create new branches
%td
%td
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Push to non-protected branches
%td
%td
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Remove non-protected branches
%td
%td
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Add tags
%td
%td
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Write a wiki
%td
%td
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Manage issue tracker
%td
%td
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Add new team members
%td
%td
%td
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Push to protected branches
%td
%td
%td
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Remove protected branches
%td
%td
%td
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Edit project
%td
%td
%td
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Add Deploy Keys to project
%td
%td
%td
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Configure Project Hooks
%td
%td
%td
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Switch visibility level
%td
%td
%td
%td
%td.permission-x ✓
%tr
%td Transfer project to another namespace
%td
%td
%td
%td
%td.permission-x ✓
%tr
%td Remove project
%td
%td
%td
%td
%td.permission-x ✓
%h4 Group
%table.table
%thead
%tr
%th Action
%th Guest
%th Reporter
%th Developer
%th Master
%th Owner
%tbody
%tr
%td Browse group
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%td.permission-x ✓
%tr
%td Edit group
%td
%td
%td
%td
%td.permission-x ✓
%tr
%td Create project in group
%td
%td
%td
%td
%td.permission-x ✓
%tr
%td Manage group members
%td
%td
%td
%td
%td.permission-x ✓
%tr
%td Remove group
%td
%td
%td
%td
%td.permission-x ✓
%p.light Any user can remove himself from a group, unless he is the last Owner of the group.
.help_body
= preserve do
= markdown File.read(Rails.root.join("doc", "permissions", "permissions.md"))
app/views/help/public_access.html.haml
= render layout: 'help/layout' do
%h3.page-title Public Access
%p.slead
GitLab allows you to open selected projects to be accessed
%strong publicly
or
%strong internally
\.
%br
Projects with either of these visibility levels will be listed in the #{link_to "public access directory", public_root_path}.
%br
Internal projects will only be available to authenticated users.
.clearfix
.dashboard-intro-icon
= public_icon
%h4
Public projects
%p
Public project can be cloned
%strong without any
authentication.
%br
It will also be listed on the #{link_to "public access directory", public_root_path}.
%br
%strong Any logged in user
will have #{link_to "Guest", help_permissions_path} permissions on the repository.
.clearfix
.dashboard-intro-icon
= internal_icon
%h4
Internal projects
%p
Internal project can be cloned by any logged in user.
%br
It will also be listed on the #{link_to "public access directory", public_root_path} for logged in users.
%br
Any logged in user will have #{link_to "Guest", help_permissions_path} permissions on the repository.
%h4 How to change project visibility
%ol
%li Go to your project dashboard
%li Click on the "Edit" tab
%li Change "Visibility Level"
%h4 Visibility of users
The public page of users, located at
= succeed "," do
%code u/username
is visible if either:
%ul
%li
You are logged in.
%li
%p
You are logged out, and the target user is authorized to (is Guest, Reporter, etc.)
at least one public project.
%p 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.
.help_body
= preserve do
= markdown File.read(Rails.root.join("doc", "public_access", "public_access.md"))
app/views/help/ssh.html.haml
= render layout: 'help/layout' do
%h3.page-title SSH Keys
%p.slead
SSH key allows you to establish a secure connection between your computer and GitLab
%p.slead
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.
%p.slead
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.
%pre.dark
ssh-keygen -t rsa -C "#{current_user.email}"
%p.slead
Use code below to show your public key.
%pre.dark
cat ~/.ssh/id_rsa.pub
%p.slead
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.
.help_body
= preserve do
= markdown File.read(Rails.root.join("doc", "ssh", "ssh.md"))
app/views/help/system_hooks.html.haml
= render layout: 'help/layout' do
%h3.page-title System hooks
%p.slead
Your GitLab instance can perform HTTP POST requests on the following events: create_project, delete_project, create_user, delete_user, change_team_member.
%br
%br
System Hooks can be used, e.g. for logging or changing information in a LDAP server.
%br
%h5 Hooks request example:
= render "admin/hooks/data_ex"
.help_body
= preserve do
= markdown File.read(Rails.root.join("doc", "system_hooks", "system_hooks.md"))
app/views/help/web_hooks.html.haml
= render layout: 'help/layout' do
%h3.page-title Project web hooks
%p.light
Project web hooks allow you to trigger url if new code is pushed or new issue is created
%hr
%p.slead
You can configure web hook to listen for specific events like pushes, issues, merge requests.
%br
GitLab will send POST request with data to web hook url.
%br
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.
%hr
%h4 Push events
%p.light
Triggered when you push to the repository except pushing tags.
%br
Request body:
= highlight_js do
:erb
{
"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,
};
%h4.prepend-top-20 Issues events
%p.light
Triggered when new issue created or existing issue was updated/closed/reopened.
%br
Request body:
= highlight_js do
:erb
{
"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
}
}
%h4.prepend-top-20 Merge request events
%p.light
Triggered when new merge request created or existing merge request was updated/merged/closed.
%br
Request body:
= highlight_js do
:erb
{
"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":""
}
}
.help_body
= preserve do
= markdown File.read(Rails.root.join("doc", "web_hooks", "web_hooks.md"))
app/views/help/workflow.html.haml
= render layout: 'help/layout' do
%h3.page-title Workflow
%h4 Summary
%ol.help
%li
%p Clone project
.bash
%pre.dark
git clone git@example.com:project-name.git
%li
%p Create branch with your feature
.bash
%pre.dark
git checkout -b $feature_name
%li
%p Write code. Commit changes
.bash
%pre.dark
git commit -am "My feature is ready"
%li
%p Push your branch to GitLab
.bash
%pre.dark
git push origin $feature_name
%li
%p Review your code on Commits page
%li
%p Create a merge request
%li
%p Your team lead will review code & merge it to main branch
%h3 Authorization for Merge Requests
%p
There are two main ways to have a merge request flow with GitLab: working with protected branches in a single repository, or working with forks of an authoritative project.
%h4 Protected branch flow
%p
With the protected branch flow everybody works within the same GitLab project.
The project maintainers get Master access and the regular developers get Developer access.
The maintainers mark the authoritative branches as 'Protected'.
The developers push feature branches to the project and create merge requests to have their feature branches reviewed and merged into one of the protected branches.
Only users with Master access can merge changes into a protected branch.
%h5 Advantages
%ul
%li fewer projects means less clutter
%li developers need to consider only one remote repository
%h5 Disadvantages
%ul
%li manual setup of protected branch required for each new project
%h4 Forking workflow
%p
With the forking workflow the maintainers get Master access and the regular developers get Reporter access to the authoritative repository, which prohibits them from pushing any changes to it.
Developers create forks of the authoritative project and push their feature branches to their own forks.
To get their changes into master they need to create a merge request across forks.
%h5 Advantages
%ul
%li in an appropriately configured GitLab group, new projects automatically get the required access restrictions for regular developers: fewer manual steps to configure authorization for new projects
%h5 Disadvantages
%ul
%li all developers on the project need to keep their forks up to date, which requires more advanced Git skills (managing multiple remotes)
.help_body
= preserve do
= markdown File.read(Rails.root.join("doc", "workflow", "workflow.md"))
doc/permissions/permissions.md 0 → 100644
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.
doc/public_access/public_access.md 0 → 100644
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.
doc/ssh/ssh.md 0 → 100644
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.
app/views/admin/hooks/_data_ex.html.haml → doc/system_hooks/system_hooks.md
= highlight_js do
:erb
1. Project created:
{
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",
......@@ -10,10 +16,13 @@
"path": "stormcloud",
"path_with_namespace": "jsmith/stormcloud",
"project_id": 74,
}
}
```
**Project destroyed:**
2. Project destroyed:
{
```json
{
"created_at": "2012-07-21T07:30:58Z",
"event_name": "project_destroy",
"name": "Underscore",
......@@ -22,10 +31,13 @@
"path": "underscore",
"path_with_namespace": "jsmith/underscore",
"project_id": 73,
}
}
```
3. New Team Member:
{
**New Team Member:**
```ruby
{
"created_at": "2012-07-21T07:30:56Z",
"event_name": "user_add_to_team",
"project_access": "Master",
......@@ -34,10 +46,13 @@
"project_path": "storecloud",
"user_email": "johnsmith@gmail.com",
"user_name": "John Smith",
}
}
```
**Team Member Removed:**
4. Team Member Removed:
{
```json
{
"created_at": "2012-07-21T07:30:56Z",
"event_name": "user_remove_from_team",
"project_access": "Master",
......@@ -46,22 +61,29 @@
"project_path": "storecloud",
"user_email": "johnsmith@gmail.com",
"user_name": "John Smith",
}
}
```
5. User created:
{
**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:**
6. User removed:
{
```json
{
"created_at": "2012-07-21T07:44:07Z",
"email": "js@gitlabhq.com",
"event_name": "user_destroy",
"name": "John Smith",
"user_id": 41
}
}
```
doc/web_hooks/web_hooks.md 0 → 100644
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": ""
}
}
```
doc/workflow/workflow.md 0 → 100644
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
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment