diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api/README.md | 9 | ||||
| -rw-r--r-- | doc/api/projects.md | 2 | ||||
| -rw-r--r-- | doc/ci/runners/README.md | 214 | ||||
| -rw-r--r-- | doc/ci/runners/img/shared_runners_admin.png | bin | 0 -> 29192 bytes | |||
| -rw-r--r-- | doc/ci/runners/project_specific.png | bin | 30196 -> 0 bytes | |||
| -rw-r--r-- | doc/ci/runners/shared_runner.png | bin | 17797 -> 0 bytes | |||
| -rw-r--r-- | doc/ci/triggers/README.md | 160 | ||||
| -rw-r--r-- | doc/ci/triggers/img/triggers_page.png | bin | 110560 -> 20857 bytes | |||
| -rw-r--r-- | doc/ci/variables/README.md | 1 | ||||
| -rw-r--r-- | doc/ci/yaml/README.md | 6 | ||||
| -rw-r--r-- | doc/development/README.md | 2 | ||||
| -rw-r--r-- | doc/development/polymorphic_associations.md | 146 | ||||
| -rw-r--r-- | doc/development/single_table_inheritance.md | 18 | ||||
| -rw-r--r-- | doc/user/project/img/protected_branches_delete.png | bin | 0 -> 21510 bytes | |||
| -rw-r--r-- | doc/user/project/protected_branches.md | 27 |
15 files changed, 421 insertions, 164 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index e1d4009dedc..2175b305e02 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -55,6 +55,15 @@ following locations: - [V3 to V4](v3_to_v4.md) - [Version](version.md) +## Road to GraphQL + +API v4 will be the last REST API that we support. Going forward, we will start +on moving to GraphQL and deprecate the use of controller-specific +endpoints. GraphQL has a number of benefits: + +1. We avoid having to maintain two different APIs. +2. Callers of the API can request only what they need. + ### Internal CI API The following documentation is for the [internal CI API](ci/README.md): diff --git a/doc/api/projects.md b/doc/api/projects.md index 0debdcfae89..bf21aa0e179 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -415,6 +415,8 @@ Parameters: Forks a project into the user namespace of the authenticated user or the one provided. +The forking operation for a project is asynchronous and is completed in a background job. The request will return immediately. To determine whether the fork of the project has completed, query the `import_status` for the new project. + ``` POST /projects/:id/fork ``` diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 1bd1ee93ac5..73aee3c3f56 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -1,124 +1,168 @@ # Runners -In GitLab CI, Runners run your [yaml](../yaml/README.md). -A Runner is an isolated (virtual) machine that picks up jobs -through the coordinator API of GitLab CI. +In GitLab CI, Runners run the code defined in [`.gitlab-ci.yml`](../yaml/README.md). +They are isolated (virtual) machines that pick up jobs through the coordinator +API of GitLab CI. A Runner can be specific to a certain project or serve any project in GitLab CI. A Runner that serves all projects is called a shared Runner. -Ideally, GitLab Runner should not be installed on the same machine as GitLab. +Ideally, the GitLab Runner should not be installed on the same machine as GitLab. Read the [requirements documentation](../../install/requirements.md#gitlab-runner) for more information. -## Shared vs. Specific Runners - -A Runner that is specific only runs for the specified project. A shared Runner -can run jobs for every project that has enabled the option **Allow shared Runners**. - -**Shared Runners** are useful for jobs that have similar requirements, -between multiple projects. Rather than having multiple Runners idling for -many projects, you can have a single or a small number of Runners that handle -multiple projects. This makes it easier to maintain and update Runners. - -**Specific Runners** are useful for jobs that have special requirements or for -projects with a specific demand. If a job has certain requirements, you can set -up the specific Runner with this in mind, while not having to do this for all -Runners. For example, if you want to deploy a certain project, you can setup -a specific Runner to have the right credentials for this. - -Projects with high demand of CI activity can also benefit from using specific Runners. -By having dedicated Runners you are guaranteed that the Runner is not being held -up by another project's jobs. +## Shared vs specific Runners + +After [installing the Runner][install], you can either register it as shared or +specific. You can only register a shared Runner if you have admin access to +the GitLab instance. The main differences between a shared and a specific Runner +are: + +- **Shared Runners** are useful for jobs that have similar requirements, + between multiple projects. Rather than having multiple Runners idling for + many projects, you can have a single or a small number of Runners that handle + multiple projects. This makes it easier to maintain and update them. + Shared Runners process jobs using a [fair usage queue](#how-shared-runners-pick-jobs). + In contrast to specific Runners that use a FIFO queue, this prevents + cases where projects create hundreds of jobs which can lead to eating all + available shared Runners resources. +- **Specific Runners** are useful for jobs that have special requirements or for + projects with a specific demand. If a job has certain requirements, you can set + up the specific Runner with this in mind, while not having to do this for all + Runners. For example, if you want to deploy a certain project, you can setup + a specific Runner to have the right credentials for this. The [usage of tags](#using-tags) + may be useful in this case. Specific Runners process jobs using a [FIFO] queue. + +A Runner that is specific only runs for the specified project(s). A shared Runner +can run jobs for every project that has enabled the option **Allow shared Runners** +under **Settings ➔ Pipelines**. + +Projects with high demand of CI activity can also benefit from using specific +Runners. By having dedicated Runners you are guaranteed that the Runner is not +being held up by another project's jobs. You can set up a specific Runner to be used by multiple projects. The difference with a shared Runner is that you have to enable each project explicitly for the Runner to be able to run its jobs. Specific Runners do not get shared with forked projects automatically. -A fork does copy the CI settings (jobs, allow shared, etc) of the cloned repository. - -# Creating and Registering a Runner - -There are several ways to create a Runner. Only after creation, upon -registration its status as Shared or Specific is determined. - -[See the documentation for](https://docs.gitlab.com/runner/install) -the different methods of installing a Runner instance. +A fork does copy the CI settings (jobs, allow shared, etc) of the cloned +repository. -After installing the Runner, you can either register it as `Shared` or as `Specific`. -You can only register a Shared Runner if you have admin access to the GitLab instance. +## Registering a shared Runner -## Registering a Shared Runner +You can only register a shared Runner if you are an admin of the GitLab instance. -You can only register a shared Runner if you are an admin on the linked -GitLab instance. +1. Grab the shared-Runner token on the `admin/runners` page -Grab the shared-Runner token on the `admin/runners` page of your GitLab CI -instance. +  - +1. [Register the Runner][register] -Now simply register the Runner as any Runner: +Shared Runners are enabled by default as of GitLab 8.2, but can be disabled +with the **Disable shared Runners** button which is present under each project's +**Settings ➔ Pipelines** page. Previous versions of GitLab defaulted shared +Runners to disabled. -``` -sudo gitlab-ci-multi-runner register -``` - -Shared Runners are enabled by default as of GitLab 8.2, but can be disabled with the -`DISABLE SHARED RUNNERS` button. Previous versions of GitLab defaulted shared Runners to -disabled. - -## Registering a Specific Runner +## Registering a specific Runner Registering a specific can be done in two ways: 1. Creating a Runner with the project registration token 1. Converting a shared Runner into a specific Runner (one-way, admin only) -There are several ways to create a Runner instance. The steps below only -concern registering the Runner on GitLab CI. - -### Registering a Specific Runner with a Project Registration token +### Registering a specific Runner with a project registration token To create a specific Runner without having admin rights to the GitLab instance, -visit the project you want to make the Runner work for in GitLab CI. +visit the project you want to make the Runner work for in GitLab: -Click on the Runner tab and use the registration token you find there to -setup a specific Runner for this project. +1. Go to **Settings ➔ Pipelines** to obtain the token +1. [Register the Runner][register] - +### Making an existing shared Runner specific -To register the Runner, run the command below and follow instructions: +If you are an admin on your GitLab instance, you can turn any shared Runner into +a specific one, but not the other way around. Keep in mind that this is a one +way transition. -``` -sudo gitlab-ci-multi-runner register -``` +1. Go to the Runners in the admin area **Overview ➔ Runners** (`/admin/runners`) + and find your Runner +1. Enable any projects under **Restrict projects for this Runner** to be used + with the Runner -### Lock a specific Runner from being enabled for other projects +From now on, the shared Runner will be specific to those projects. + +## Locking a specific Runner from being enabled for other projects You can configure a Runner to assign it exclusively to a project. When a Runner is locked this way, it can no longer be enabled for other projects. -This setting is available on each Runner in *Project Settings* > *Runners*. +This setting can be enabled the first time you [register a Runner][register] and +can be changed afterwards under each Runner's settings. + +To lock/unlock a Runner: + +1. Visit your project's **Settings ➔ Pipelines** +1. Find the Runner you wish to lock/unlock and make sure it's enabled +1. Click the pencil button +1. Check the **Lock to current projects** option +1. Click **Save changes** for the changes to take effect -### Making an existing Shared Runner Specific +## How shared Runners pick jobs -If you are an admin on your GitLab instance, -you can make any shared Runner a specific Runner, _but you can not -make a specific Runner a shared Runner_. +Shared Runners abide to a process queue we call fair usage. The fair usage +algorithm tries to assign jobs to shared Runners from projects that have the +lowest number of jobs currently running on shared Runners. -To make a shared Runner specific, go to the Runner page (`/admin/runners`) -and find your Runner. Add any projects on the left to make this Runner -run exclusively for these projects, therefore making it a specific Runner. +**Example 1** - +We have following jobs in queue: -## Using Shared Runners Effectively +- job 1 for project 1 +- job 2 for project 1 +- job 3 for project 1 +- job 4 for project 2 +- job 5 for project 2 +- job 6 for project 3 + +With the fair usage algorithm jobs are assigned in following order: + +1. We choose job 1, because project 1 doesn't run currently any jobs and has the lowest job number from projects that doesn't run jobs +1. We choose job 4, because project 2 doesn't run currently any jobs and has the lowest job number from projects that doesn't run jobs +1. We choose job 6, because project 3 doesn't run currently any jobs and has the lowest job number from projects that doesn't run jobs +1. We choose job 2, because project 1 as other it runs 1 job +1. We choose job 5, because project 2 runs 1 job, where project 1 runs 2 jobs now +1. We choose job 3, because project 1 and runs 2 jobs + +--- + +**Example 2** + +We have following jobs in queue: + +- job 1 for project 1 +- job 2 for project 1 +- job 3 for project 1 +- job 4 for project 2 +- job 5 for project 2 +- job 6 for project 3 + +With the fair usage algorithm jobs are assigned in following order: + +1. We choose job 1, because project 1 doesn't run currently any jobs and has the lowest job number from projects that doesn't run jobs +1. We finish job 1 +1. We choose job 2, because project 1 doesn't run currently any jobs and has the lowest job number from projects that doesn't run jobs +1. We choose job 4, because project 2 doesn't run currently any jobs and has the lowest job number from projects that doesn't run jobs +1. We finish job 4 +1. We choose job 5, because project 2 doesn't run currently any jobs and has the lowest job number from projects that doesn't run jobs +1. We choose job 6, because project 3 doesn't run currently any jobs +1. We choose job 3, because project 1, 2 and 3 runs exactly one job now + +## Using shared Runners effectively If you are planning to use shared Runners, there are several things you should keep in mind. -### Use Tags +### Using tags You must setup a Runner to be able to run all the different types of jobs that it may encounter on the projects it's shared over. This would be @@ -130,17 +174,27 @@ shared Runners will only run the jobs they are equipped to run. For instance, at GitLab we have Runners tagged with "rails" if they contain the appropriate dependencies to run Rails test suites. -### Prevent Runner with tags from picking jobs without tags +### Preventing Runners with tags from picking jobs without tags You can configure a Runner to prevent it from picking jobs with tags when -the Runner does not have tags assigned. This setting is available on each -Runner in *Project Settings* > *Runners*. +the Runner does not have tags assigned. This setting can be enabled the first +time you [register a Runner][register] and can be changed afterwards under +each Runner's settings. + +To make a Runner pick tagged/untagged jobs: + +1. Visit your project's **Settings ➔ Pipelines** +1. Find the Runner you wish and make sure it's enabled +1. Click the pencil button +1. Check the **Run untagged jobs** option +1. Click **Save changes** for the changes to take effect ### Be careful with sensitive information If you can run a job on a Runner, you can get access to any code it runs and get the token of the Runner. With shared Runners, this means that anyone -that runs jobs on the Runner, can access anyone else's code that runs on the Runner. +that runs jobs on the Runner, can access anyone else's code that runs on the +Runner. In addition, because you can get access to the Runner token, it is possible to create a clone of a Runner and submit false jobs, for example. @@ -160,3 +214,7 @@ project. Mentioned briefly earlier, but the following things of Runners can be exploited. We're always looking for contributions that can mitigate these [Security Considerations](https://docs.gitlab.com/runner/security/). + +[install]: http://docs.gitlab.com/runner/install/ +[fifo]: https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics) +[register]: http://docs.gitlab.com/runner/register/ diff --git a/doc/ci/runners/img/shared_runners_admin.png b/doc/ci/runners/img/shared_runners_admin.png Binary files differnew file mode 100644 index 00000000000..e049b339b36 --- /dev/null +++ b/doc/ci/runners/img/shared_runners_admin.png diff --git a/doc/ci/runners/project_specific.png b/doc/ci/runners/project_specific.png Binary files differdeleted file mode 100644 index c812defa67b..00000000000 --- a/doc/ci/runners/project_specific.png +++ /dev/null diff --git a/doc/ci/runners/shared_runner.png b/doc/ci/runners/shared_runner.png Binary files differdeleted file mode 100644 index 31574a17764..00000000000 --- a/doc/ci/runners/shared_runner.png +++ /dev/null diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index cb646827fb4..7ec7136d8c6 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -4,15 +4,22 @@ - [Introduced][ci-229] in GitLab CE 7.14. - GitLab 8.12 has a completely redesigned job permissions system. Read all about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#job-triggers). -- GitLab 9.0 introduced a trigger ownership to solve permission problems. -Triggers can be used to force a rebuild of a specific `ref` (branch or tag) -with an API call. +Triggers can be used to force a pipeline rerun of a specific `ref` (branch or +tag) with an API call. -## Add a trigger +## Authentication tokens + +The following methods of authentication are supported. + +### Trigger token + +A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger). + +## Adding a new trigger You can add a new trigger by going to your project's -**Settings ➔ Pipelines ➔ Triggers**. The **Add trigger** button will +**Settings ➔ Pipelines** under **Triggers**. The **Add trigger** button will create a new token which you can then use to trigger a rerun of this particular project's pipeline. @@ -22,7 +29,10 @@ overview of the time the triggers were last used.  -## Take ownership +## Taking ownership of a trigger + +> **Note**: +GitLab 9.0 introduced a trigger ownership to solve permission problems. Each created trigger when run will impersonate their associated user including their access to projects and their project permissions. @@ -30,26 +40,20 @@ their access to projects and their project permissions. You can take ownership of existing triggers by clicking *Take ownership*. From now on the trigger will be run as you. -## Legacy triggers - -Old triggers, created before 9.0 will be marked as Legacy. Triggers with -the legacy label do not have an associated user and only have access -to the current project. - -Legacy trigger are considered deprecated and will be removed -with one of the future versions of GitLab. - -## Revoke a trigger +## Revoking a trigger You can revoke a trigger any time by going at your project's -**Settings > Triggers** and hitting the **Revoke** button. The action is -irreversible. +**Settings ➔ Pipelines** under **Triggers** and hitting the **Revoke** button. +The action is irreversible. -## Trigger a pipeline +## Triggering a pipeline -> **Note**: -Valid refs are only the branches and tags. If you pass a commit SHA as a ref, -it will not trigger a job. +> **Notes**: +- Valid refs are only the branches and tags. If you pass a commit SHA as a ref, + it will not trigger a job. +- If your project is public, passing the token in plain text is probably not the + wisest idea, so you might want to use a + [secret variable](../variables/README.md#secret-variables) for that purpose. To trigger a job you need to send a `POST` request to GitLab's API endpoint: @@ -57,11 +61,11 @@ To trigger a job you need to send a `POST` request to GitLab's API endpoint: POST /projects/:id/trigger/pipeline ``` -The required parameters are the trigger's `token` and the Git `ref` on which -the trigger will be performed. Valid refs are the branch and the tag. The `:id` -of a project can be found by [querying the API](../../api/projects.md) -or by visiting the **Pipelines** settings page which provides -self-explanatory examples. +The required parameters are the [trigger's `token`](#authentication-tokens) +and the Git `ref` on which the trigger will be performed. Valid refs are the +branch and the tag. The `:id` of a project can be found by +[querying the API](../../api/projects.md) or by visiting the **Pipelines** +settings page which provides self-explanatory examples. When a rerun of a pipeline is triggered, the information is exposed in GitLab's UI under the **Jobs** page and the jobs are marked as triggered 'by API'. @@ -78,46 +82,7 @@ below. --- -See the [Examples](#examples) section for more details on how to actually -trigger a rebuild. - -## Trigger a pipeline from webhook - -> Introduced in GitLab 8.14. - -To trigger a job from webhook of another project you need to add the following -webhook url for Push and Tag push events: - -``` -https://gitlab.example.com/api/v4/projects/:id/ref/:ref/trigger/pipeline?token=TOKEN -``` - -> **Note**: -- `ref` should be passed as part of url in order to take precedence over `ref` - from webhook body that designates the branchref that fired the trigger in the source repository. -- `ref` should be url encoded if contains slashes. - -## Pass job variables to a trigger - -You can pass any number of arbitrary variables in the trigger API call and they -will be available in GitLab CI so that they can be used in your `.gitlab-ci.yml` -file. The parameter is of the form: - -``` -variables[key]=value -``` - -This information is also exposed in the UI. - - - ---- - -See the [Examples](#examples) section below for more details. - -## Examples - -Using cURL you can trigger a rebuild with minimal effort, for example: +By using cURL you can trigger a pipeline rerun with minimal effort, for example: ```bash curl --request POST \ @@ -135,8 +100,6 @@ curl --request POST \ "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline?token=TOKEN&ref=master" ``` -### Triggering a pipeline within `.gitlab-ci.yml` - You can also benefit by using triggers in your `.gitlab-ci.yml`. Let's say that you have two projects, A and B, and you want to trigger a rebuild on the `master` branch of project B whenever a tag on project A is created. This is the job you @@ -156,14 +119,37 @@ Now, whenever a new tag is pushed on project A, the job will run and the `stage: deploy` ensures that this job will run only after all jobs with `stage: test` complete successfully. -_**Note:** If your project is public, passing the token in plain text is -probably not the wisest idea, so you might want to use a -[secure variable](../variables/README.md#user-defined-variables-secure-variables) -for that purpose._ +## Triggering a pipeline from a webhook -### Making use of trigger variables +> **Notes**: +- Introduced in GitLab 8.14. +- `ref` should be passed as part of the URL in order to take precedence over + `ref` from the webhook body that designates the branch ref that fired the + trigger in the source repository. +- `ref` should be URL-encoded if it contains slashes. -Using trigger variables can be proven useful for a variety of reasons. +To trigger a job from a webhook of another project you need to add the following +webhook URL for Push and Tag events (change the project ID, ref and token): + +``` +https://gitlab.example.com/api/v4/projects/9/ref/master/trigger/pipeline?token=TOKEN +``` + +## Making use of trigger variables + +You can pass any number of arbitrary variables in the trigger API call and they +will be available in GitLab CI so that they can be used in your `.gitlab-ci.yml` +file. The parameter is of the form: + +``` +variables[key]=value +``` + +This information is also exposed in the UI. + + + +Using trigger variables can be proven useful for a variety of reasons: * Identifiable jobs. Since the variable is exposed in the UI you can know why the rebuild was triggered if you pass a variable that explains the @@ -208,15 +194,7 @@ curl --request POST \ https://gitlab.example.com/api/v4/projects/9/trigger/pipeline ``` -### Using a webhook to trigger a pipeline - -You can add the following webhook to another project in order to trigger a job: - -``` -https://gitlab.example.com/api/v4/projects/9/ref/master/trigger/pipeline?token=TOKEN&variables[UPLOAD_TO_S3]=true -``` - -### Using cron to trigger nightly pipelines +## Using cron to trigger nightly pipelines >**Note:** The following behavior can also be achieved through GitLab's UI with @@ -230,4 +208,18 @@ branch of project with ID `9` every night at `00:30`: 30 0 * * * curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline ``` +## Legacy triggers + +Old triggers, created before GitLab 9.0 will be marked as legacy. + +Triggers with the legacy label do not have an associated user and only have +access to the current project. They are considered deprecated and will be +removed with one of the future versions of GitLab. You are advised to +[take ownership](#taking-ownership) of any legacy triggers. + +[ee-2017]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2017 [ci-229]: https://gitlab.com/gitlab-org/gitlab-ci/merge_requests/229 +[ee]: https://about.gitlab.com/gitlab-ee/ +[variables]: ../variables/README.md +[predef]: ../variables/README.md#predefined-variables-environment-variables +[registry]: ../../user/project/container_registry.md diff --git a/doc/ci/triggers/img/triggers_page.png b/doc/ci/triggers/img/triggers_page.png Binary files differindex eafd8519a23..7dc8f91cf7e 100644 --- a/doc/ci/triggers/img/triggers_page.png +++ b/doc/ci/triggers/img/triggers_page.png diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 76ba78ea7be..d1f9881e51b 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -431,3 +431,4 @@ export CI_REGISTRY_PASSWORD="longalfanumstring" [protected branches]: ../../user/project/protected_branches.md [protected tags]: ../../user/project/protected_tags.md [shellexecutors]: https://docs.gitlab.com/runner/executors/ +[eep]: https://about.gitlab.com/gitlab-ee/ "Available only in GitLab Enterprise Edition Premium" diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index fc813694ff2..8a0662db6fd 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -393,7 +393,8 @@ There are a few rules that apply to the usage of refs policy: * `only` and `except` are inclusive. If both `only` and `except` are defined in a job specification, the ref is filtered by `only` and `except`. * `only` and `except` allow the use of regular expressions. -* `only` and `except` allow the use of special keywords: `branches`, `tags`, and `triggers`. +* `only` and `except` allow the use of special keywords: +`api`, `branches`, `external`, `tags`, `pushes`, `schedules`, `triggers`, and `web` * `only` and `except` allow to specify a repository path to filter jobs for forks. @@ -411,7 +412,7 @@ job: ``` In this example, `job` will run only for refs that are tagged, or if a build is -explicitly requested via an API trigger. +explicitly requested via an API trigger or a [Pipeline Schedule](../../user/project/pipelines/schedules.md). ```yaml job: @@ -419,6 +420,7 @@ job: only: - tags - triggers + - schedules ``` The repository path can be used to have jobs executed only for the parent diff --git a/doc/development/README.md b/doc/development/README.md index af4131c4a8f..40addfd8a4c 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -51,6 +51,8 @@ - [Post Deployment Migrations](post_deployment_migrations.md) - [Foreign Keys & Associations](foreign_keys.md) - [Serializing Data](serializing_data.md) +- [Polymorphic Associations](polymorphic_associations.md) +- [Single Table Inheritance](single_table_inheritance.md) ## i18n diff --git a/doc/development/polymorphic_associations.md b/doc/development/polymorphic_associations.md new file mode 100644 index 00000000000..d63b9fb115f --- /dev/null +++ b/doc/development/polymorphic_associations.md @@ -0,0 +1,146 @@ +# Polymorphic Associations + +**Summary:** always use separate tables instead of polymorphic associations. + +Rails makes it possible to define so called "polymorphic associations". This +usually works by adding two columns to a table: a target type column, and a +target id. For example, at the time of writing we have such a setup for +`members` with the following columns: + +* `source_type`: a string defining the model to use, can be either `Project` or + `Namespace`. +* `source_id`: the ID of the row to retrieve based on `source_type`. For + example, when `source_type` is `Project` then `source_id` will contain a + project ID. + +While such a setup may appear to be useful, it comes with many drawbacks; enough +that you should avoid this at all costs. + +## Space Wasted + +Because this setup relies on string values to determine the model to use it will +end up wasting a lot of space. For example, for `Project` and `Namespace` the +maximum size is 9 bytes, plus 1 extra byte for every string when using +PostgreSQL. While this may only be 10 bytes per row, given enough tables and +rows using such a setup we can end up wasting quite a bit of disk space and +memory (for any indexes). + +## Indexes + +Because our associations are broken up into two columns this may result in +requiring composite indexes for queries to be performed efficiently. While +composite indexes are not wrong at all, they can be tricky to set up as the +ordering of columns in these indexes is important to ensure optimal performance. + +## Consistency + +One really big problem with polymorphic associations is being unable to enforce +data consistency on the database level using foreign keys. For consistency to be +enforced on the database level one would have to write their own foreign key +logic to support polymorphic associations. + +Enforcing consistency on the database level is absolutely crucial for +maintaining a healthy environment, and thus is another reason to avoid +polymorphic associations. + +## Query Overhead + +When using polymorphic associations you always need to filter using both +columns. For example, you may end up writing a query like this: + +```sql +SELECT * +FROM members +WHERE source_type = 'Project' +AND source_id = 13083; +``` + +Here PostgreSQL can perform the query quite efficiently if both columns are +indexed, but as the query gets more complex it may not be able to use these +indexes efficiently. + +## Mixed Responsibilities + +Similar to functions and classes a table should have a single responsibility: +storing data with a certain set of pre-defined columns. When using polymorphic +associations you are instead storing different types of data (possibly with +different columns set) in the same table. + +## The Solution + +Fortunately there is a very simple solution to these problems: simply use a +separate table for every type you would otherwise store in the same table. Using +a separate table allows you to use everything a database may provide to ensure +consistency and query data efficiently, without any additional application logic +being necessary. + +Let's say you have a `members` table storing both approved and pending members, +for both projects and groups, and the pending state is determined by the column +`requested_at` being set or not. Schema wise such a setup can lead to various +columns only being set for certain rows, wasting space. It's also possible that +certain indexes will only be set for certain rows, again wasting space. Finally, +querying such a table requires less than ideal queries. For example: + +```sql +SELECT * +FROM members +WHERE requested_at IS NULL +AND source_type = 'GroupMember' +AND source_id = 4 +``` + +Instead such a table should be broken up into separate tables. For example, you +may end up with 4 tables in this case: + +* project_members +* group_members +* pending_project_members +* pending_group_members + +This makes querying data trivial. For example, to get the members of a group +you'd run: + +```sql +SELECT * +FROM group_members +WHERE group_id = 4 +``` + +To get all the pending members of a group in turn you'd run: + +```sql +SELECT * +FROM pending_group_members +WHERE group_id = 4 +``` + +If you want to get both you can use a UNION, though you need to be explicit +about what columns you want to SELECT as otherwise the result set will use the +columns of the first query. For example: + +```sql +SELECT id, 'Group' AS target_type, group_id AS target_id +FROM group_members + +UNION ALL + +SELECT id, 'Project' AS target_type, project_id AS target_id +FROM project_members +``` + +The above example is perhaps a bit silly, but it shows that there's nothing +stopping you from merging the data together and presenting it on the same page. +Selecting columns explicitly can also speed up queries as the database has to do +less work to get the data (compared to selecting all columns, even ones you're +not using). + +Our schema also becomes easier. No longer do we need to both store and index the +`source_type` column, we can define foreign keys easily, and we don't need to +filter rows using the `IS NULL` condition. + +To summarize: using separate tables allows us to use foreign keys effectively, +create indexes only where necessary, conserve space, query data more +efficiently, and scale these tables more easily (e.g. by storing them on +separate disks). A nice side effect of this is that code can also become easier +as you won't end up with a single model having to handle different kinds of +data. diff --git a/doc/development/single_table_inheritance.md b/doc/development/single_table_inheritance.md new file mode 100644 index 00000000000..27c3c4f3199 --- /dev/null +++ b/doc/development/single_table_inheritance.md @@ -0,0 +1,18 @@ +# Single Table Inheritance + +**Summary:** don't use Single Table Inheritance (STI), use separate tables +instead. + +Rails makes it possible to have multiple models stored in the same table and map +these rows to the correct models using a `type` column. This can be used to for +example store two different types of SSH keys in the same table. + +While tempting to use one should avoid this at all costs for the same reasons as +outlined in the document ["Polymorphic Associations"](polymorphic_associations.md). + +## Solution + +The solution is very simple: just use a separate table for every type you'd +otherwise store in the same table. For example, instead of having a `keys` table +with `type` set to either `Key` or `DeployKey` you'd have two separate tables: +`keys` and `deploy_keys`. diff --git a/doc/user/project/img/protected_branches_delete.png b/doc/user/project/img/protected_branches_delete.png Binary files differnew file mode 100644 index 00000000000..cfdfe6c6c29 --- /dev/null +++ b/doc/user/project/img/protected_branches_delete.png diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 7650020b37e..0570d9f471f 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -94,8 +94,33 @@ all matching branches:  +## Deleting a protected branch + +> [Introduced][ce-21393] in GitLab 9.3. + +From time to time, it may be required to delete or clean up branches that are +protected. + +User with [Master permissions][perm] and up can manually delete protected +branches via GitLab's web interface: + +1. Visit **Repository > Branches** +1. Click on the delete icon next to the branch you wish to delete +1. In order to prevent accidental deletion, an additional confirmation is + required + +  + +Deleting a protected branch is only allowed via the web interface, not via Git. +This means that you can't accidentally delete a protected branch from your +command line or a Git client application. + ## Changelog +**9.2** + +- Allow deletion of protected branches via the web interface [gitlab-org/gitlab-ce#21393][ce-21393] + **8.11** - Allow creating protected branches that can't be pushed to [gitlab-org/gitlab-ce!5081][ce-5081] @@ -110,4 +135,6 @@ all matching branches: [ce-4665]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4665 "Allow specifying protected branches using wildcards" [ce-4892]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4892 "Allow developers to merge into a protected branch without having push access" [ce-5081]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5081 "Allow creating protected branches that can't be pushed to" +[ce-21393]: https://gitlab.com/gitlab-org/gitlab-ce/issues/21393 [ee-restrict]: http://docs.gitlab.com/ee/user/project/protected_branches.html#restricting-push-and-merge-access-to-certain-users +[perm]: ../permissions.md |
