diff options
| -rw-r--r-- | doc/README.md | 2 | ||||
| -rw-r--r-- | doc/administration/incoming_email.md | 2 | ||||
| -rw-r--r-- | doc/administration/repository_storage_paths.md | 4 | ||||
| -rw-r--r-- | doc/ci/merge_request_pipelines/index.md | 2 | ||||
| -rw-r--r-- | doc/ci/yaml/README.md | 347 | ||||
| -rw-r--r-- | doc/development/architecture.md | 4 | ||||
| -rw-r--r-- | doc/development/documentation/index.md | 178 | ||||
| -rw-r--r-- | doc/subscriptions/index.md | 90 | ||||
| -rw-r--r-- | doc/topics/autodevops/index.md | 47 | ||||
| -rw-r--r-- | doc/topics/autodevops/upgrading_postgresql.md | 6 | ||||
| -rw-r--r-- | doc/user/admin_area/license.md | 27 | ||||
| -rw-r--r-- | doc/user/application_security/dast/index.md | 31 | ||||
| -rw-r--r-- | doc/user/project/pages/getting_started/pages_bundled_template.md | 33 | ||||
| -rw-r--r-- | doc/user/project/pages/getting_started/pages_new_project_template.md | 34 | ||||
| -rw-r--r-- | doc/user/project/pages/index.md | 2 |
15 files changed, 515 insertions, 294 deletions
diff --git a/doc/README.md b/doc/README.md index fe38b6cb419..65044edff53 100644 --- a/doc/README.md +++ b/doc/README.md @@ -121,7 +121,7 @@ The following documentation relates to the DevOps **Plan** stage: | [Related Issues](user/project/issues/related_issues.md) **(STARTER)** | Create a relationship between issues. | | [Requirements Management](user/project/requirements/index.md) **(ULTIMATE)** | Check your products against a set of criteria. | | [Roadmap](user/group/roadmap/index.md) **(ULTIMATE)** | Visualize epic timelines. | -| [Service Desk](user/project/service_desk.md) **(PREMIUM)** | A simple way to allow people to create issues in your GitLab instance without needing their own user account. | +| [Service Desk](user/project/service_desk.md) **(STARTER)** | A simple way to allow people to create issues in your GitLab instance without needing their own user account. | | [Time Tracking](user/project/time_tracking.md) | Track time spent on issues and merge requests. | | [Todos](user/todos.md) | Keep track of work requiring attention with a chronological list displayed on a simple dashboard. | diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index e078a7c1098..48b92b595d9 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -17,7 +17,7 @@ GitLab has several features based on receiving incoming emails: allow GitLab users to create a new merge request by sending an email to a user-specific email address. - [Service Desk](../user/project/service_desk.md): provide e-mail support to - your customers through GitLab. **(PREMIUM)** + your customers through GitLab. **(STARTER)** ## Requirements diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index 9b397e93290..b682c064b70 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -110,8 +110,8 @@ Once you set the multiple storage paths, you can choose where new repositories will be stored under **Admin Area > Settings > Repository > Repository storage > Storage nodes for new repositories**. -Each storage can be assigned a weight from 0-100. When a new project is created, these weights will be used -to determine the storage location the repository will be created. +Each storage can be assigned a weight from 0-100. When a new project is created, these +weights are used to determine the storage location the repository will be created on.  diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index 7a4ca989fb6..d77cfbc1ebb 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -207,7 +207,7 @@ The variable names begin with the `CI_MERGE_REQUEST_` prefix. ### Two pipelines created when pushing to a merge request If you are experiencing duplicated pipelines when using `rules`, take a look at -the [key details when using `rules`](../yaml/README.md#key-details-when-using-rules), +the [important differences between `rules` and `only`/`except`](../yaml/README.md#differences-between-rules-and-onlyexcept), which will help you get your starting configuration correct. If you are seeing two pipelines when using `only/except`, please see the caveats diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 770329ac6be..6fb8a551c08 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -1037,113 +1037,293 @@ the `.template` job, and uses the `alpine` Docker image as defined in the local > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3. -`rules` allows for a list of individual rule objects to be evaluated -*in order*, until one matches and dynamically provides attributes to the job. +The `rules` keyword is a way to set job policies that determine whether or not jobs +are added to pipelines. + +A list of individual rule clauses are evaluated *in order*, until one matches. When +matched, the job is either included or excluded from the pipeline, depending +on the configuration. If included, the job also has [certain attributes](#rules-attributes) +added to it. CAUTION: **Caution:** -`rules` can't be used in combination with `only/except` as it is a replacement for that functionality. If you attempt to do this, the linter will return a +`rules` can't be used in combination with [`only/except`](#onlyexcept-basic) because it is a replacement for +that functionality. If you attempt to do this, the linter returns a `key may not be used with rules` error. -#### Key details when using `rules` +#### Rules attributes -A very important difference between `rules` and `only/except`, is that jobs defined -with `rules` trigger merge request pipelines by default, but `only/except` jobs do not. -This may be surprising if migrating from `only` and `except`, so new users of `rules` -can use one of the [`workflow: rules` templates](#workflowrules-templates) to get started. -This will ensure that the behavior is more stable as you start adding additional `rules` -blocks, and will avoid issues like creating a duplicate, merge request (detached) pipeline. +The job attributes allowed by `rules` are: -We don't recommend mixing `only/except` jobs with `rules` jobs in the same pipeline. -It may not cause YAML errors, but debugging the exact execution behavior can be complex -due to the different default behaviors of `only/except` and `rules`. +- [`when`](#when): If not defined, defaults to `when: on_success`. + - If used as `when: delayed`, `start_in` is also required. +- [`allow_failure`](#allow_failure): If not defined, defaults to `allow_failure: false`. -### Rules clauses +If `when` is evaluated to any value except `never`, the job is included in the pipeline. -Available rule clauses include: +For example: -- [`if`](#rulesif) (similar to [`only:variables`](#onlyvariablesexceptvariables)) -- [`changes`](#ruleschanges) (same as [`only:changes`](#onlychangesexceptchanges)) -- [`exists`](#rulesexists) +```yaml +docker build: + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + rules: + - if: '$CI_COMMIT_BRANCH == "master"' + when: delayed + start_in: '3 hours' + allow_failure: true +``` -For example, using `if`. This configuration specifies that `job` should be built -and run for every pipeline on merge requests targeting `master`, regardless of -the status of other builds: +Additional job configuration may be added to rules in the future. If something +useful is not available, please [open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues). + +#### Rules clauses + +Available rule clauses are: + +| Clause | Description | +|----------------------------|------------------------------------------------------------------------------------------------------------------------------------| +| [`if`](#rulesif) | Add or exclude jobs from a pipeline by evaluating an `if` statement. Similar to [`only:variables`](#onlyvariablesexceptvariables). | +| [`changes`](#ruleschanges) | Add or exclude jobs from a pipeline based on what files are changed. Same as [`only:changes`](#onlychangesexceptchanges). | +| [`exists`](#rulesexists) | Add or exclude jobs from a pipeline based on the presence of specific files. | + +Rules are evaluated in order until a match is found. If a match is found, the attributes +are checked to see if the job should be added to the pipeline. If no attributes are defined, +the defaults are: + +- `when: on_success` +- `allow_failure: false` + +The job is added to the pipeline: + +- If a rule matches and has `when: on_success`, `when: delayed` or `when: always`. +- If no rules match, but the last clause is `when: on_success`, `when: delayed` + or `when: always` (with no rule). + +The job is not added to the pipeline: + +- If no rules match, and there is no standalone `when: on_success`, `when: delayed` or + `when: always`. +- If a rule matches, and has `when: never` as the attribute. + +For example, using `if` clauses to strictly limit when jobs run: ```yaml job: script: "echo Hello, Rules!" rules: - - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' - when: always - - if: '$VAR =~ /pattern/' + - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' when: manual + allow_failure: true + - if: '$CI_PIPELINE_SOURCE == "schedule"' +``` + +In this example: + +- If the pipeline is for a merge request, the first rule matches, and the job + is added to the [merge request pipeline](../merge_request_pipelines/index.md) + with attributes of: + - `when: manual` (manual job) + - `allow_failure: true` (allows the pipeline to continue running even if the manual job is not run) +- If the pipeline is **not** for a merge request, the first rule doesn't match, and the + second rule is evaluated. +- If the pipeline is a scheduled pipeline, the second rule matches, and the job + is added to the scheduled pipeline. Since no attributes were defined, it is added + with: + - `when: on_success` (default) + - `allow_failure: false` (default) +- In **all other cases**, no rules match, so the job is **not** added to any other pipeline. + +Alternatively, you can define a set of rules to exclude jobs in a few cases, but +run them in all other cases: + +```yaml +job: + script: "echo Hello, Rules!" + rules: + - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' + when: never + - if: '$CI_PIPELINE_SOURCE == "schedule"' + when: never - when: on_success ``` -In this example, if the first rule: +- If the pipeline is for a merge request, the job is **not** be added to the pipeline. +- If the pipeline is a scheduled pipeline, the job is **not** be added to the pipeline. +- In **all other cases**, the job is added to the pipeline, with `when: on_success`. + +CAUTION: **Caution** +If you use `when: on_success`, `always`, or `delayed` as the final rule, two +simultaneous pipelines may start. Both push pipelines and merge request pipelines can +be triggered by the same event (a push to the source branch for an open merge request). +See the [important differences between `rules` and `only`/`except`](#differences-between-rules-and-onlyexcept) +for more details. + +#### Differences between `rules` and `only`/`except` + +A very important difference between `rules` and `only/except`, is that jobs defined +with `only/except` do not trigger merge request pipelines without explicit configuration. +`rules` *can* trigger all types of pipelines, without explicitly configuring each +type. + +For example: + +```yaml +job: + script: "echo This creates double pipelines!" + rules: + - if: '$CUSTOM_VARIABLE == "false"' + when: never + - when: always +``` + +This job does not run when `$CUSTOM_VARIABLE` is false, but it *does* run in **all** +other pipelines, including **both** push (branch) and merge request pipelines. With +this configuration, every push to an open merge request's source branch +causes duplicated pipelines. Explicitly allowing both push and merge request pipelines +in the same job could have the same effect. + +We recommend using [`workflow: rules`](#workflowrules) to limit which types of pipelines +are permitted. Allowing only merge request pipelines, or only branch pipelines, +eliminates duplicated pipelines. Alternatively, you can rewrite the rules to be +stricter, or avoid using a final `when` (`always`, `on_success` or `delayed`). -- Matches, the job will be given the `when:always` attribute. -- Does not match, the second and third rules will be evaluated sequentially - until a match is found. That is, the job will be given either the: - - `when: manual` attribute if the second rule matches. **The stage won't complete until this manual job is triggered and completes successfully.** - - `when: on_success` attribute if the second rule does not match. The third - rule will always match when reached because it has no conditional clauses. +Also, we don't recommend mixing `only/except` jobs with `rules` jobs in the same pipeline. +It may not cause YAML errors, but debugging the exact execution behavior can be complex +due to the different default behaviors of `only/except` and `rules`. + +##### `rules:if` + +`rules:if` clauses determine whether or not jobs are added to a pipeline by evaluating +a simple `if` statement. If the `if` statement is true, the job is either included +or excluded from a pipeline. In plain English, `if` rules can be interpreted as one of: -#### `rules:if` +- "If this rule evaluates to true, add the job" (default). +- "If this rule evaluates to true, do not add the job" (by adding `when: never`). `rules:if` differs slightly from `only:variables` by accepting only a single -expression string, rather than an array of them. Any set of expressions to be -evaluated should be conjoined into a single expression using `&&` or `||`, and use +expression string per rule, rather than an array of them. Any set of expressions to be +evaluated can be conjoined into a single expression by using `&&` or `||`, and use the [variable matching syntax](../variables/README.md#syntax-of-environment-variable-expressions). +`if:` clauses are evaluated based on the values of [predefined environment variables](../variables/predefined_variables.md) +or [custom environment variables](../variables/README.md#custom-environment-variables). + For example: ```yaml job: script: "echo Hello, Rules!" rules: - - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' # This rule will be evaluated + - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' when: always - - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/' # This rule will only be evaluated if the target branch is not "master" + - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/' when: manual - - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME' # If neither of the first two match but the simple presence does, we set to "on_success" by default + allow_failure: true + - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME' # Checking for the presence of a variable is possible ``` Some details regarding the logic that determines the `when` for the job: -- If none of the provided rules match, the job is set to `when: never`, and is +- If none of the provided rules match, the job is set to `when: never` and is not included in the pipeline. - A rule without any conditional clause, such as a `when` or `allow_failure` rule without `if` or `changes`, always matches, and is always used if reached. -- If a rule matches and has no `when` defined, the rule will use the `when` +- If a rule matches and has no `when` defined, the rule uses the `when` defined for the job, which defaults to `on_success` if not defined. -#### `rules:changes` +For behavior similar to the [`only`/`except` keywords](#onlyexcept-basic), you can +check the value of the `$CI_PIPELINE_SOURCE` variable. + +| Value | Description | +|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `push` | For pipelines triggered by a `git push` event, including for branches and tags. | +| `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. | +| `trigger` | For pipelines created by using a trigger token. | +| `schedule` | For [scheduled pipelines](../pipelines/schedules.md). | +| `api` | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). | +| `external` | When using CI services other than GitLab. | +| `pipelines` | For multi-project pipelines created by [using the API with `CI_JOB_TOKEN`](../triggers/README.md#when-used-with-multi-project-pipelines). | +| `chat` | For pipelines created by using a [GitLab ChatOps](../chatops/README.md) command. | +| `webide` | For pipelines created by using the [WebIDE](../../user/project/web_ide/index.md). | +| `merge_request_event` | For pipelines created when a merge request is created or updated. Required to enable [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). | +| `external_pull_request_event` | When an external pull request on GitHub is created or updated. See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). | +| `parent_pipeline` | For pipelines triggered by a [parent/child pipeline](../parent_child_pipelines.md) with `rules`, use this in the child pipeline configuration so that it can be triggered by the parent pipeline. | + +For example: + +```yaml +job: + script: "echo Hello, Rules!" + rules: + - if: '$CI_PIPELINE_SOURCE == "schedule"' + when: manual + allow_failure: true + - if: '$CI_PIPELINE_SOURCE == "push"' +``` + +This example runs the job as a manual job in scheduled pipelines or in push +pipelines (to branches or tags), with `when: on_success` (default). It does not +add the job to any other pipeline type. + +Another example: + +```yaml +job: + script: "echo Hello, Rules!" + rules: + - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' + - if: '$CI_PIPELINE_SOURCE == "schedule"' +``` + +This example runs the job as a `when: on_success` job in [merge request pipelines](../merge_request_pipelines/index.md) +and scheduled pipelines. It does not run in any other pipeline type. + +Other commonly used variables for `if` clauses: + +- `if: $CI_COMMIT_TAG`: If changes are pushed for a tag. +- `if: $CI_COMMIT_BRANCH`: If changes are pushed to any branch. +- `if: '$CI_COMMIT_BRANCH == "master"'`: If changes are pushed to `master`. +- `if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'`: If changes are pushed to the default + branch (usually `master`). Useful if reusing the same configuration in multiple + projects with potentially different default branches. +- `if: '$CI_COMMIT_BRANCH =~ /regex-expression/'`: If the commit branch matches a regular expression. +- `if: '$CUSTOM_VARIABLE !~ /regex-expression/'`: If the [custom variable](../variables/README.md#custom-environment-variables) + `CUSTOM_VARIABLE` does **not** match a regular expression. +- `if: '$CUSTOM_VARIABLE == "value1"'`: If the custom variable `CUSTOM_VARIABLE` is + exactly `value1`. -`rules: changes` works exactly the same way as `only: changes` and `except: changes`, -accepting an array of paths. Similarly, it will always return true if there is no -Git push event. See [`only/except: changes`](#onlychangesexceptchanges) for more information. +##### `rules:changes` + +To determine if jobs should be added to a pipeline, `rules: changes` clauses check +the files changed by Git push events. + +`rules: changes` works exactly the same way as [`only: changes` and `except: changes`](#onlychangesexceptchanges), +accepting an array of paths. Similarly, it always returns true if there is no +Git push event. It should only be used for branch pipelines or merge request pipelines. For example: ```yaml +workflow: + rules: + - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' + docker build: script: docker build -t my-image:$CI_COMMIT_REF_SLUG . rules: - - changes: # Will include the job and set to when:manual if any of the follow paths match a modified file. + - changes: - Dockerfile when: manual - - if: '$VAR == "string value"' - when: manual # Will include the job and set to when:manual if the expression evaluates to true, after the `changes:` rule fails to match. - - when: on_success # If neither of the first rules match, set to on_success + allow_failure: true ``` -In this example, a job either set to: +In this example: -- Run manually if `Dockerfile` has changed OR `$VAR == "string value"`. -- `when:on_success` by the last rule, where no earlier clauses evaluate to true. +- [`workflow: rules`](#workflowrules) allows only pipelines for merge requests for all jobs. +- If `Dockerfile` has changed, add the job to the pipeline as a manual job, and allow the pipeline + to continue running even if the job is not triggered (`allow_failure: true`). +- If `Dockerfile` has not changed, do not add job to any pipeline (same as `when: never`). -#### `rules:exists` +##### `rules:exists` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4. @@ -1177,7 +1357,7 @@ NOTE: **Note:** For performance reasons, using `exists` with patterns is limited to 10000 checks. After the 10000th check, rules with patterned globs will always match. -#### `rules:allow_failure` +##### `rules:allow_failure` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) in GitLab 12.8. @@ -1223,47 +1403,12 @@ docker build: # - when: never would be redundant here, this is implied any time rules are listed. ``` -The only clauses currently available are: - -- `if` -- `changes` -- `exists` - Keywords such as `branches` or `refs` that are currently available for `only`/`except` are not yet available in `rules` as they are being individually considered for their usage and behavior in this context. Future keyword improvements are being discussed in our [epic for improving `rules`](https://gitlab.com/groups/gitlab-org/-/epics/2783), where anyone can add suggestions or requests. -#### Permitted attributes - -The only job attributes currently set by `rules` are: - -- `when`. -- `start_in`, if `when` is set to `delayed`. -- `allow_failure`. - -A job will be included in a pipeline if `when` is evaluated to any value -except `never`. - -Delayed jobs require a `start_in` value, so rule objects do as well. For -example: - -```yaml -docker build: - script: docker build -t my-image:$CI_COMMIT_REF_SLUG . - rules: - - changes: # Will include the job and delay 3 hours when the Dockerfile has changed - - Dockerfile - when: delayed - start_in: '3 hours' - - when: on_success # Otherwise include the job and set to run normally -``` - -Additional job configuration may be added to rules in the future. If something -useful is not available, please -[open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues). - ### `only`/`except` (basic) NOTE: **Note:** @@ -1288,20 +1433,20 @@ There are a few rules that apply to the usage of job policy: In addition, `only` and `except` allow the use of special keywords: -| **Value** | **Description** | -| --------- | ---------------- | -| `branches` | When a Git reference of a pipeline is a branch. | -| `tags` | When a Git reference of a pipeline is a tag. | -| `api` | When pipeline has been triggered by a second pipelines API (not triggers API). | -| `external` | When using CI services other than GitLab. | -| `pipelines` | For multi-project triggers, created using the API with `CI_JOB_TOKEN`. | -| `pushes` | Pipeline is triggered by a `git push` by the user. | -| `schedules` | For [scheduled pipelines](../pipelines/schedules.md). | -| `triggers` | For pipelines created using a trigger token. | -| `web` | For pipelines created using **Run pipeline** button in GitLab UI (under your project's **Pipelines**). | -| `merge_requests` | When a merge request is created or updated (See [pipelines for merge requests](../merge_request_pipelines/index.md)). | -| `external_pull_requests`| When an external pull request on GitHub is created or updated (See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests)). | -| `chat` | For jobs created using a [GitLab ChatOps](../chatops/README.md) command. | +| **Value** | **Description** | +|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `branches` | When the Git reference for a pipeline is a branch. | +| `tags` | When the Git reference for a pipeline is a tag. | +| `api` | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). | +| `external` | When using CI services other than GitLab. | +| `pipelines` | For multi-project pipelines created by using the API with `CI_JOB_TOKEN`. | +| `pushes` | For pipelines triggered by a `git push` event, including for branches and tags. | +| `schedules` | For [scheduled pipelines](../pipelines/schedules.md). | +| `triggers` | For pipelines created by using a trigger token. | +| `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. | +| `merge_requests` | For pipelines created when a merge request is created or updated. Enables [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). | +| `external_pull_requests` | When an external pull request on GitHub is created or updated (See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests)). | +| `chat` | For pipelines created by using a [GitLab ChatOps](../chatops/README.md) command. | In the example below, `job` will run only for refs that start with `issue-`, whereas all branches will be skipped: diff --git a/doc/development/architecture.md b/doc/development/architecture.md index f0ce033587d..4f7f05e0179 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -773,7 +773,7 @@ response back to the user directly. When referring to `~git` in the pictures it means the home directory of the Git user which is typically `/home/git`. -GitLab is primarily installed within the `/home/git` user home directory as `git` user. Within the home directory is where the gitlabhq server software resides as well as the repositories (though the repository location is configurable). +GitLab is primarily installed within the `/home/git` user home directory as `git` user. Within the home directory is where the GitLab server software resides as well as the repositories (though the repository location is configurable). The bare repositories are located in `/home/git/repositories`. GitLab is a Ruby on rails application so the particulars of the inner workings can be learned by studying how a Ruby on rails application works. @@ -849,7 +849,7 @@ Usage: /etc/init.d/postgresql {start|stop|restart|reload|force-reload|status} [v ### Log locations of the services -gitlabhq (includes Unicorn and Sidekiq logs): +GitLab (includes Unicorn and Sidekiq logs): - `/home/git/gitlab/log/` contains `application.log`, `production.log`, `sidekiq.log`, `unicorn.stdout.log`, `git_json.log` and `unicorn.stderr.log` normally. diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index f845a6ec592..e2c042f9c2e 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -492,122 +492,138 @@ The output should be similar to: Note that this requires you to either have the required lint tools installed on your machine, or a working Docker installation, in which case an image with these tools pre-installed will be used. -### Local linting +### Local linters To help adhere to the [documentation style guidelines](styleguide.md), and improve the content -added to documentation, consider locally installing and running documentation linters. This will -help you catch common issues before raising merge requests for review of documentation. +added to documentation, [install documentation linters](#install-linters) and +[integrate them with your code editor](#configure-editors). -Running the following locally allows you to match the checks in the build pipeline: +At GitLab, we mostly use: -- [markdownlint](#markdownlint). -- [Vale](#vale). - -NOTE: **Note:** -This list does not limit what other linters you can add to your local documentation writing toolchain. +- [markdownlint](#markdownlint) +- [Vale](#vale) #### markdownlint -[markdownlint](https://github.com/DavidAnson/markdownlint) checks that Markdown -syntax follows [certain rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules), -and is used by the [`docs-lint` test](#testing) with a [configuration file](#markdownlint-configuration). -Our [Documentation Style Guide](styleguide.md#markdown) and [Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) -elaborate on which choices must be made when selecting Markdown syntax for GitLab -documentation. This tool helps catch deviations from those guidelines. - -markdownlint can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--), -either on a single Markdown file or on all Markdown files in a project. For example, to run -markdownlint on all documentation in the [`gitlab` project](https://gitlab.com/gitlab-org/gitlab), -run the following commands from within your `gitlab` project root directory, which will -automatically detect the [`.markdownlint.json`](#markdownlint-configuration) configuration -file in the root of the project, and test all files in `/doc` and its subdirectories: - -```shell -markdownlint 'doc/**/*.md' -``` +[markdownlint](https://github.com/DavidAnson/markdownlint) checks that Markdown syntax follows +[certain rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules), and is +used by the [`docs-lint` test](#testing). -If you wish to use a different configuration file, use the `-c` flag: +Our [Documentation Style Guide](styleguide.md#markdown) and +[Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) elaborate on which choices must +be made when selecting Markdown syntax for GitLab documentation. This tool helps catch deviations +from those guidelines. -```shell -markdownlint -c <config-file-name> 'doc/**/*.md' -``` +markdownlint configuration is found in the following projects: -##### Run markdownlint in an editor +- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.markdownlint.json) +- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/.markdownlint.json) +- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.markdownlint.json) +- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.markdownlint.json) +- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/.markdownlint.json) -markdownlint can also be run as a linter within text editors using [plugins/extensions](https://github.com/DavidAnson/markdownlint#related), -such as: +This configuration is also used within build pipelines. -- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) -- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) -- [Atom](https://atom.io/packages/linter-node-markdownlint) +You can use markdownlint: -It is best to use the [same configuration file](#markdownlint-configuration) as what -is in use in the four repositories that are the sources for <https://docs.gitlab.com>. Each -plugin/extension has different requirements regarding the configuration file, which -is explained in each editor's docs. +- [On the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--). +- [Within a code editor](#configure-editors). -##### markdownlint configuration +#### Vale -Each formatting issue that markdownlint checks has an associated -[rule](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules). -These rules are configured in the `.markdownlint.json` files located in the root of -four repositories that are the sources for <https://docs.gitlab.com>: +[Vale](https://errata-ai.gitbook.io/vale/) is a grammar, style, and word usage linter for the +English language. Vale's configuration is stored in the +[`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) file located in the root +directory of projects. -- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.markdownlint.json) -- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/.markdownlint.json) -- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.markdownlint.json) -- [`charts`](https://gitlab.com/charts/gitlab/blob/master/.markdownlint.json) +Vale supports creating [custom tests](https://errata-ai.github.io/vale/styles/) that extend any of +several types of checks, which we store in the `.linting/vale/styles/gitlab` directory within the +documentation directory of projects. -By default all rules are enabled, so the configuration file is used to disable unwanted -rules, and also to configure optional parameters for enabled rules as needed. You can -also check [the issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64352) that -tracked the changes required to implement these rules, and details which rules were -on or off when markdownlint was enabled on the docs. +Vale configuration is found in the following projects: -#### Vale +- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab) +- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/master/docs/.vale/gitlab) +- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/tree/master/doc/.vale/gitlab) +- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/tree/master/doc/.vale/gitlab) +- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/master/doc/.vale/gitlab) -[Vale](https://errata-ai.gitbook.io/vale/) is a grammar, style, and word usage linter -for the English language. Vale's configuration is stored in the -[`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) file -located in the root directory of the [GitLab repository](https://gitlab.com/gitlab-org/gitlab). +This configuration is also used within build pipelines. -Vale supports creating [custom tests](https://errata-ai.github.io/vale/styles/), -stored in the `doc/.linting/vale/styles/gitlab` directory, that extend any of -several types of checks. +You can use Vale: -To view linting suggestions locally, you must install Vale on your own machine, -and from GitLab's root directory (where `.vale.ini` is located), run: +- [On the command line](https://errata-ai.gitbook.io/vale/getting-started/usage). +- [Within a code editor](#configure-editors). -```shell -vale --glob='*.{md}' doc -``` +#### Install linters + +At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in +build pipelines: -Vale's error-level test results [are displayed](#testing) in CI pipelines. +1. Install `markdownlint-cli`, using either: -##### Run Vale in an editor + - `npm`: + + ```shell + npm install -g markdownlint-cli + ``` + + - `yarn`: + + ```shell + yarn global add markdownlint-cli + ``` + + We recommend installing the version of `markdownlint-cli` currently used in the documentation + linting [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/dockerfiles/Dockerfile.gitlab-docs-lint#L38). + +1. Install [`vale`](https://github.com/errata-ai/vale/releases). For example, to install using + `brew` for macOS, run: + + ```shell + brew install vale + ``` + + We recommend installing the version of Vale currently used in the documentation linting + [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/dockerfiles/Dockerfile.gitlab-docs-lint#L16). + +In addition to using markdownlint and Vale at the command line, these tools can be +[integrated with your code editor](#configure-editors). + +#### Configure editors + +To configure markdownlint within your editor, install one of the following as appropriate: + +- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) +- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) +- [Atom](https://atom.io/packages/linter-node-markdownlint) -You can run Vale as a linter within your text editor of choice, with: +To configure Vale within your editor, install one of the following as appropriate: - The Sublime Text [`SublimeLinter-contrib-vale` plugin](https://packagecontrol.io/packages/SublimeLinter-contrib-vale) - The Visual Studio Code [`testthedocs.vale` extension](https://marketplace.visualstudio.com/items?itemName=testthedocs.vale) We don't use [Vale Server](https://errata-ai.github.io/vale/#using-vale-with-a-text-editor-or-another-third-party-application). -##### Disable a Vale test +#### Disable Vale tests -You can disable a specific Vale linting rule or all Vale linting rules for any portion of a document: +You can disable a specific Vale linting rule or all Vale linting rules for any portion of a +document: -- To disable a specific rule, add a `<!-- vale gitlab.rulename = NO -->` tag - before the text, and a `<!-- vale gitlab.rulename = YES -->` tag after the text, - replacing `rulename` with the filename of a test in the [GitLab styles](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.linting/vale/styles/gitlab) directory. -- To disable all Vale linting rules, add a `<!-- vale off -->` tag before the text, - and a `<!-- vale on -->` tag after the text. +- To disable a specific rule, add a `<!-- vale gitlab.rulename = NO -->` tag before the text, and a + `<!-- vale gitlab.rulename = YES -->` tag after the text, replacing `rulename` with the filename + of a test in the + [GitLab styles](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.linting/vale/styles/gitlab) + directory. +- To disable all Vale linting rules, add a `<!-- vale off -->` tag before the text, and a + `<!-- vale on -->` tag after the text. -Whenever possible, exclude only the problematic rule and line(s). -In some cases, such as list items, you may need to disable linting for the entire -list until ["Ignore comments are not honored in a Markdown file"](https://github.com/errata-ai/vale/issues/175) is resolved. +Whenever possible, exclude only the problematic rule and line(s). In some cases, such as list items, +you may need to disable linting for the entire list until +[Vale issue #175](https://github.com/errata-ai/vale/issues/175) is resolved. -For more information, see [Vale's documentation](https://errata-ai.gitbook.io/vale/getting-started/markup#markup-based-configuration). +For more information, see +[Vale's documentation](https://errata-ai.gitbook.io/vale/getting-started/markup#markup-based-configuration). ## Danger Bot diff --git a/doc/subscriptions/index.md b/doc/subscriptions/index.md index 0425fe98d27..0d77a2fe3c3 100644 --- a/doc/subscriptions/index.md +++ b/doc/subscriptions/index.md @@ -22,13 +22,13 @@ When choosing a subscription, consider the following factors: ### Choosing a GitLab tier -Pricing is [tier-based](https://about.gitlab.com/pricing/), allowing you to choose the features which fit your budget. See the [feature comparison](https://about.gitlab.com/pricing/gitlab-com/feature-comparison/) for information on what features are available at each tier. +Pricing is [tier-based](https://about.gitlab.com/pricing/), allowing you to choose the features which fit your budget. See the [GitLab.com feature comparison](https://about.gitlab.com/pricing/gitlab-com/feature-comparison/) and the [self-managed feature comparison](https://about.gitlab.com/pricing/self-managed/feature-comparison/) for information on what features are available at each tier for each product. ### Choosing between GitLab.com or self-managed There are some differences in how a subscription applies, depending if you use GitLab.com or a self-managed instance. -- [GitLab.com](#gitlabcom): GitLab's software-as-a-service offering. You don't need to install anything to use GitLab.com, you only need to [sign up](https://gitlab.com/users/sign_in) and start using GitLab straight away. +- [GitLab.com](#gitlabcom): GitLab's software-as-a-service offering. You don't need to install anything to use GitLab.com, you only need to [sign up](https://gitlab.com/users/sign_up) and start using GitLab straight away. - [GitLab self-managed](#self-managed): Install, administer, and maintain your own GitLab instance. On a self-managed instance, a GitLab subscription provides the same set of features for all users. On GitLab.com you can apply a subscription to either a group or a personal namespace. @@ -103,10 +103,11 @@ To subscribe to GitLab.com: 1. Select the **Bronze**, **Silver**, or **Gold** GitLab.com plan through the [Customers Portal](https://customers.gitlab.com/). 1. Link your GitLab.com account with your Customers Portal account. - Once signed into the Customers Portal, if your account is not + Once a plan has been selected, if your account is not already linked, you will be prompted to link your account with a - **Link my GitLab Account** button. -1. Associate the group with the subscription. + **Sign in to GitLab.com** button. +1. Select the namespace from the drop-down list to associate the subscription. +1. Proceed to checkout. TIP: **Tip:** You can also go to the [**My Account**](https://customers.gitlab.com/customers/edit) @@ -129,19 +130,20 @@ instance, ensure you're purchasing enough seats to With the [Customers Portal](https://customers.gitlab.com/) you can: -- [Change billing information](#change-billing-information) +- [Change billing and company information](#change-billing-information) - [Change the payment method](#change-payment-method) - [Change the linked account](#change-the-linked-account) - [Change the associated namespace](#change-the-associated-namespace) +- [Change customers portal account password](#change-customer-portal-account-password) ### Change billing information To change billing information: 1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). -1. Go to the **My Account** page. +1. Select the **My account** drop-down and click on **Payment methods**. 1. Make the required changes to the **Account Details** information. -1. Click **Update Account**. +1. Click **Save changes**. NOTE: **Note:** Future purchases will use the information in this section. @@ -166,8 +168,7 @@ account: [Customers Portal](https://customers.gitlab.com/customers/sign_in). 1. Go to [GitLab.com](https://gitlab.com) in a separate browser tab. Ensure you are not logged in. -1. On the Customers Portal page, click - [**My Account**](https://customers.gitlab.com/customers/edit) in the top menu. +1. On the Customers Portal page, select the **My account** drop-down and click on [**Account details**](https://customers.gitlab.com/customers/edit). 1. Under **Your GitLab.com account**, click **Change linked account** button. 1. Log in to the [GitLab.com](https://gitlab.com) account you want to link to the Customers Portal. @@ -177,12 +178,21 @@ With a linked GitLab.com account: 1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). 1. Navigate to the **Manage Purchases** page. -1. Click **Change linked group**. +1. Click **Change linked namespace**. 1. Select the desired group from the **This subscription is for** dropdown. 1. Click **Proceed to checkout**. Subscription charges are calculated based on the total number of users in a group, including its subgroups and nested projects. If the total number of users exceeds the number of seats in your subscription, you will be charged for the additional users. +### Change customer portal account password + +To change the password for this customers portal account: + +1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). +1. Select the **My account** drop-down and click on **Account details**. +1. Make the required changes to the **Your password** section. +1. Click **Save changes**. + ## View your subscription ### View your GitLab.com subscription @@ -224,8 +234,8 @@ To renew your subscription, [prepare for renewal by reviewing your account](#pre The [Customers Portal](https://customers.gitlab.com/customers/sign_in) is your tool for renewing and modifying your subscription. Before going ahead with renewal, log in and verify or update: -- The invoice contact details on the **My Account** page. -- The credit card on file in the **Payment Methods** page. +- The invoice contact details on the **Account details** page. +- The credit card on file on the **Payment Methods** page. TIP: **Tip:** Contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) if you need assistance accessing the Customers Portal or if you need to change the contact person who manages your subscription. @@ -241,7 +251,7 @@ A GitLab subscription is valid for a specific number of users. For details, see ##### Purchase additional seats for GitLab.com -There is no self-service option for purchasing additional seats. You must request a quotation from GitLab Sales. To do so, contact GitLab via our [support form](https://support.gitlab.com/hc/en-us/requests/new) and select **Licensing and Renewals Problems** from the menu. +There is no self-service option for purchasing additional seats. You must request a quotation from GitLab Sales. To do so, contact GitLab via our [support form](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293). The amount charged per seat is calculated by one of the following methods: @@ -255,8 +265,8 @@ Self-managed instances can add users to a subscription any time during the subsc To add users to a subscription: 1. Log in to the [Customers Portal](https://customers.gitlab.com/). -1. Select **Manage Purchases**. -1. Select **Add more seats**. +1. Navigate to the **Manage Purchases** page. +1. Select **Add more seats** on the relevant subscription card. 1. Enter the number of additional users. 1. Select **Proceed to checkout**. 1. Review the **Subscription Upgrade Detail**. The system lists the total price for all users on the system and a credit for what you've already paid. You will only be charged for the net change. @@ -264,7 +274,7 @@ To add users to a subscription: The following will be emailed to you: -- A payment receipt. You can also access this information in the Customers Portal under **Payment History**. +- A payment receipt. You can also access this information in the Customers Portal under [**View invoices**](https://customers.gitlab.com/receipts). - A new license. [Upload this license](../user/admin_area/license.md#uploading-your-license) to your instance to use it. ### Seat Link @@ -273,7 +283,7 @@ The following will be emailed to you: Seat Link allows us to provide our self-managed customers with prorated charges for user growth throughout the year using a quarterly reconciliation process. -Seat Link sends to GitLab daily a count of all users in connected self-managed instances. That information is used to automate prorated reconciliations. The data is sent securely through an encrypted HTTPS connection. +Seat Link daily sends a count of all users in connected self-managed instances to GitLab. That information is used to automate prorated reconciliations. The data is sent securely through an encrypted HTTPS connection. Seat Link provides **only** the following information to GitLab: @@ -333,7 +343,7 @@ Sg0KU1hNMGExaE9SVGR2V2pKQlBUMWNiaUo5DQo=', You can view the exact JSON payload in the administration panel. To view the payload: -1. Navigate to **Admin Area > Settings > Metrics and profiling** and expand **Seat Links**. +1. Navigate to **Admin Area > Settings > Metrics and profiling** and expand **Seat Link**. 1. Click **Preview payload**. #### Disable Seat Link @@ -343,7 +353,7 @@ You can view the exact JSON payload in the administration panel. To view the pay Seat Link is enabled by default. To disable this feature, go to -**{admin}** **Admin Area > Settings > Metrics and profiling** and clear the **Seat Link** checkbox. +**{admin}** **Admin Area > Settings > Metrics and profiling**, uncheck the **Enable Seat Link** checkbox > **Save changes**. To disable Seat Link in an Omnibus GitLab installation, and prevent it from being configured in the future through the administration panel, set the following in @@ -379,7 +389,7 @@ To view or change automatic subscription renewal (at the same tier as the previo - If you see **Cancel subscription**, your subscription is set to automatically renew at the end of the subscription period. Click it to cancel automatic renewal. With automatic renewal enabled, the subscription will automatically renew on the expiration date and there will be no gap in available service. -An invoice will be generated for the renewal and available for viewing or download in the [Payment History](https://customers.gitlab.com/receipts) page. If you have difficulty during the renewal process, contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) for assistance. +An invoice will be generated for the renewal and available for viewing or download in the [View invoices](https://customers.gitlab.com/receipts) page. If you have difficulty during the renewal process, contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) for assistance. ### Renew a self-managed subscription @@ -410,10 +420,10 @@ We recommend following these steps during renewal: | Users over license | The number of users that exceed the `Users in License` for the current license term. Charges for this number of users will be incurred at the next renewal. | 1. Review your renewal details and complete the payment process. -1. A license for the renewal term will be available on the [Manage Purchases](https://customers.gitlab.com/subscriptions) page beneath your new subscription details. -1. [Upload](../user/admin_area/license.md) your new license to your instance. +1. A license for the renewal term will be available for download on the [Manage Purchases](https://customers.gitlab.com/subscriptions) page on the relevant subscription card. Select **Copy license to clipboard** or **Download license** to get a copy. +1. [Upload](../user/admin_area/license.md#uploading-your-license) your new license to your instance. -An invoice will be generated for the renewal and available for viewing or download in the [Payment History](https://customers.gitlab.com/receipts) page. If you have difficulty during the renewal process, contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) for assistance. +An invoice will be generated for the renewal and available for viewing or download on the [View invoices](https://customers.gitlab.com/receipts) page. If you have difficulty during the renewal process, contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) for assistance. ## Upgrade your subscription tier @@ -424,7 +434,7 @@ The process for upgrading differs depending on whether you're a GitLab.com or se To upgrade your [GitLab tier](https://about.gitlab.com/pricing/): 1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). -1. Select **Upgrade** under your subscription on the [My Account](https://customers.gitlab.com/subscriptions) page. +1. Select the **Upgrade** button on the relevant subscription card on the [Manage purchases](https://customers.gitlab.com/subscriptions) page. 1. Select the desired upgrade. 1. Confirm the active form of payment, or add a new form of payment. 1. Check the **I accept the Privacy Policy and Terms of Service** checkbox. @@ -436,8 +446,7 @@ When the purchase has been processed, you receive confirmation of your new subsc To upgrade your [GitLab tier](https://about.gitlab.com/pricing/), contact our sales team as this can't be done in the Customers Portal. You can either send an email to `renewals@gitlab.com`, or -complete the [**Contact Sales**](https://about.gitlab.com/sales/) form. Include in your message -details of which subscription you want to upgrade, and the desired tier. +complete the [**Contact Sales**](https://about.gitlab.com/sales/) form. Include details of which subscription you want to upgrade and the desired tier in your message. After messaging the sales team, the workflow is as follows: @@ -458,7 +467,7 @@ If you renew or upgrade, your data will again be accessible. ### Self-managed GitLab data -For self-managed customers, there is a two-week grace period when your features +For self-managed customers, there is a 14-day grace period when your features will continue to work as-is, after which the entire instance will become read only. @@ -467,19 +476,24 @@ features, and the instance will be read / write again. ## CI pipeline minutes -CI pipeline minutes are the execution time for your [pipelines](../ci/pipelines/index.md) on GitLab's shared runners. Each [GitLab.com tier](https://about.gitlab.com/pricing/) includes a monthly quota of CI pipeline minutes. +CI pipeline minutes are the execution time for your [pipelines](../ci/pipelines/index.md) on GitLab's shared runners. Each [GitLab.com tier](https://about.gitlab.com/pricing/) includes a monthly quota of CI pipeline minutes: + +- Free: 2,000 minutes +- Bronze: 2,000 minutes +- Silver: 10,000 minutes +- Gold: 50,000 minutes Quotas apply to: -- Groups, where the minutes are shared across all members of the group, its subgroups, and nested projects. To view the group's usage, navigate to the group, then **{settings}** **Settings > Usage Quotas**. -- Your personal account, where the minutes are available for your personal projects. To view and buy personal minutes, click your avatar, then **{settings}** **Settings > Pipeline quota**. +- Groups, where the minutes are shared across all members of the group, its subgroups, and nested projects. To view the group's usage, navigate to the group, then **{settings}** **Settings** > **Usage Quotas**. +- Your personal account, where the minutes are available for your personal projects. To view and buy personal minutes, click your avatar, then **{settings}** **Settings** > **[Usage Quotas](https://gitlab.com/profile/usage_quotas#pipelines-quota-tab)**. Only pipeline minutes for GitLab shared runners are restricted. If you have a specific runner set up for your projects, there is no limit to your build time on GitLab.com. The available quota is reset on the first of each calendar month at midnight UTC. When the CI minutes are depleted, an email is sent automatically to notify the owner(s) -of the group/namespace. You can [purchase additional CI minutes](#purchasing-additional-ci-minutes), or upgrade your account to [Silver or Gold](https://about.gitlab.com/pricing/). Your own runners can still be used even if you reach your limits. +of the namespace. You can [purchase additional CI minutes](#purchasing-additional-ci-minutes), or upgrade your account to [Silver or Gold](https://about.gitlab.com/pricing/). Your own runners can still be used even if you reach your limits. ### Purchasing additional CI minutes @@ -493,16 +507,20 @@ main quota. You can find pricing for additional CI/CD minutes in the [GitLab Cus To purchase additional minutes for your group on GitLab.com: 1. From your group, go to **{settings}** **Settings > Usage Quotas**. +1. Select **Buy additional minutes** and you will be directed to the Customers Portal. 1. Locate the subscription card that's linked to your group on GitLab.com, click **Buy more CI minutes**, and complete the details about the transaction. -1. Once we have processed your payment, the extra CI minutes will be synced to your group. +1. Once we have processed your payment, the extra CI minutes will be synced to your group namespace. 1. To confirm the available CI minutes, go to your group, then **{settings}** **Settings > Usage Quotas**. + The **Additional minutes** displayed now includes the purchased additional CI minutes, plus any minutes rolled over from last month. To purchase additional minutes for your personal namespace: -1. Click your avatar, then go to **Settings > Pipeline quota**. -1. Locate the subscription card that's linked to your personal namespace on GitLab.com, click **Buy more CI minutes**, and complete the details about the transaction. Once we have processed your payment, the extra CI minutes will be synced to your Group. -1. To confirm the available CI minutes for your personal projects, click your avatar, then go to **Settings > Pipeline quota**. +1. Click your avatar, then go to **Settings > Usage Quotas**. +1. Select **Buy additional minutes** and you will be directed to the Customers Portal. +1. Locate the subscription card that's linked to your personal namespace on GitLab.com, click **Buy more CI minutes**, and complete the details about the transaction. Once we have processed your payment, the extra CI minutes will be synced to your personal namespace. +1. To confirm the available CI minutes for your personal projects, click your avatar, then go to **Settings > Usage Quotas**. + The **Additional minutes** displayed now includes the purchased additional CI minutes, plus any minutes rolled over from last month. Be aware that: diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 767ea5ee7b7..178fd474104 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -358,6 +358,53 @@ Auto Deploy will fail if GitLab can't create a Kubernetes namespace and service account for your project. For help debugging this issue, see [Troubleshooting failed deployment jobs](../../user/project/clusters/index.md#troubleshooting). +### Detected an existing PostgreSQL database + +After upgrading to GitLab 13.0, you may encounter this message when deploying +with Auto DevOps: + +> Detected an existing PostgreSQL database installed on the +deprecated channel 1, but the current channel is set to 2. The default +channel changed to 2 in of GitLab 13.0. +> [...] + +Auto DevOps, by default, installs an in-cluster PostgreSQL database alongside +your application. The default installation method changed in GitLab 13.0, and +upgrading existing databases requires user involvement. The two installation +methods are: + +- **channel 1 (deprecated):** Pulls in the database as a dependency of the associated + Helm chart. Only supports Kubernetes versions up to version 1.15. +- **channel 2 (current):** Installs the database as an independent Helm chart. Required + for using the in-cluster database feature with Kubernetes versions 1.16 and greater. + +If you receive this error, you can do one of the following actions: + +- You can *safely* ignore the warning and continue using the channel 1 PostgreSQL + database by setting `AUTO_DEVOPS_POSTGRES_CHANNEL` to `1` and redeploying. + +- You can delete the channel 1 PostgreSQL database and install a fresh channel 2 + database by setting `AUTO_DEVOPS_POSTGRES_DELETE_V1` to a non-empty value and + redeploying. + + DANGER: **Danger:** + Deleting the channel 1 PostgreSQL database permanently deletes the existing + channel 1 database and all its data. See + [Upgrading PostgreSQL](upgrading_postgresql.md) + for more information on backing up and upgrading your database. + +- If you are not using the in-cluster database, you can set + `POSTGRES_ENABLED` to `false` and re-deploy. This option is especially relevant to + users of *custom charts without the in-chart PostgreSQL dependency*. + Database auto-detection is based on the `postgresql.enabled` Helm value for + your release. This value is set based on the `POSTGRES_ENABLED` CI variable + and persisted by Helm, regardless of whether or not your chart uses the + variable. + +DANGER: **Danger:** +Setting `POSTGRES_ENABLED` to `false` permanently deletes any existing +channel 1 database for your environment. + ## Development guides [Development guide for Auto DevOps](../../development/auto_devops.md) diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md index 893f7ba7cde..846e537e5b3 100644 --- a/doc/topics/autodevops/upgrading_postgresql.md +++ b/doc/topics/autodevops/upgrading_postgresql.md @@ -26,6 +26,9 @@ involves: This varies based on Kubernetes providers. 1. Prepare for downtime. The steps below include taking the application offline so that the in-cluster database does not get modified after the database dump is created. +1. Ensure you have not set `POSTGRES_ENABLED` to `false`, as this setting deletes + any existing channel 1 database. For more information, see + [Detected an existing PostgreSQL database](index.md#detected-an-existing-postgresql-database). TIP: **Tip:** If you have configured Auto DevOps to have staging, consider trying out the backup and restore steps on staging first, or @@ -160,8 +163,7 @@ pvc-9085e3d3-5239-11ea-9c8d-42010a8e0096 8Gi RWO Retain CAUTION: **Caution:** Using the newer version of PostgreSQL will delete the older 0.7.1 PostgreSQL. To prevent the underlying data from being -deleted, you can choose to retain the [persistent -volume](#retain-persistent-volumes). +deleted, you can choose to retain the [persistent volume](#retain-persistent-volumes). TIP: **Tip:** You can also [scope](../../ci/environments/index.md#scoping-environments-with-specs) the diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 1ffaf4e0678..4688110bbcd 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -107,14 +107,23 @@ expired license(s). It's possible to upload and view more than one license, but only the latest license will be used as the active license. -<!-- ## Troubleshooting +## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +### There is no License tab in the Admin Area -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +If you originally installed Community Edition rather than Enterprise Edition you will need to +[upgrade to Enterprise Edition](../../update/README.md#community-to-enterprise-edition) +before uploading your license. + +GitLab.com users cannot upload and use a self-managed license. If you +wish to use paid features on GitLab.com, a separate subscription may be +[purchased](../../subscriptions/index.md#subscribe-to-gitlabcom). + +### Users exceed license limit upon renewal + +If you've added new users to your GitLab instance prior to renewal you may need to +purchase additional seats to cover those users. If this is the case and a license +without enough users is uploaded a message is displayed prompting you to purchase +additional users. More information on how to determine the required number of users +and how to add additional seats can be found in the +[licensing FAQ](https://about.gitlab.com/pricing/licensing-faq/). diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index fc3dfff8a6a..87db2eba42e 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -414,6 +414,10 @@ variables: ### Customizing the DAST settings +CAUTION: **Deprecation:** +Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) +is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. + The DAST settings can be changed through environment variables by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. These variables are documented in [available variables](#available-variables). @@ -432,31 +436,6 @@ variables: Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable will take precedence. -### Overriding the DAST template - -CAUTION: **Deprecation:** -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) -is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. - -If you want to override the job definition (for example, change properties like -`variables` or `dependencies`), you need to declare a `dast` job after the -template inclusion and specify any additional keys under it. For example: - -```yaml -include: - - template: DAST.gitlab-ci.yml - -dast: - stage: dast # IMPORTANT: don't forget to add this - variables: - DAST_WEBSITE: https://example.com - CI_DEBUG_TRACE: "true" -``` - -As the DAST job belongs to a separate `dast` stage that runs after all -[default stages](../../../ci/yaml/README.md#stages), -don't forget to add `stage: dast` when you override the template job definition. - ### Available variables DAST can be [configured](#customizing-the-dast-settings) using environment variables. @@ -549,7 +528,7 @@ A DAST job has two executing processes: Debug mode of the scripts can be enabled by using the `DAST_DEBUG` environment variable. This can help when troubleshooting the job, and will output statements indicating what percentage of the scan is complete. -For details on using variables, see [Overriding the DAST template](#overriding-the-dast-template). +For details on using variables, see [Overriding the DAST template](#customizing-the-dast-settings). Debug mode of the ZAP server can be enabled using the `DAST_ZAP_LOG_CONFIGURATION` environment variable. The following table outlines examples of values that can be set and the effect that they have on the output that is logged. diff --git a/doc/user/project/pages/getting_started/pages_bundled_template.md b/doc/user/project/pages/getting_started/pages_bundled_template.md index cfa4e0910db..bc706105606 100644 --- a/doc/user/project/pages/getting_started/pages_bundled_template.md +++ b/doc/user/project/pages/getting_started/pages_bundled_template.md @@ -1,34 +1,5 @@ --- -type: reference, howto -stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +redirect_to: 'pages_new_project_template.md' --- -# Create a Pages website from a new project template - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47857) in GitLab 11.8. - -GitLab provides templates for the most popular Static Site Generators (SSGs). -You can create a new project from a template and run the CI/CD pipeline to generate a Pages website. - -Use a template when you want to test GitLab Pages or start a new project that's already -configured to generate a Pages site. - -1. From the top navigation, click the **+** button and select **New project**. -1. Select **Create from Template**. -1. Next to one of the templates starting with **Pages**, click **Use template**. - -  - -1. Complete the form and click **Create project**. -1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** - and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your - site. - -The site can take approximately 30 minutes to deploy. -When the pipeline is finished, go to **Settings > Pages** to find the link to -your Pages website. - -For every change pushed to your repository, GitLab CI/CD runs a new pipeline -that immediately publishes your changes to the Pages site. +This document was moved to [pages_new_project_template.md](pages_new_project_template.md). diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md new file mode 100644 index 00000000000..cfa4e0910db --- /dev/null +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -0,0 +1,34 @@ +--- +type: reference, howto +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Create a Pages website from a new project template + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47857) in GitLab 11.8. + +GitLab provides templates for the most popular Static Site Generators (SSGs). +You can create a new project from a template and run the CI/CD pipeline to generate a Pages website. + +Use a template when you want to test GitLab Pages or start a new project that's already +configured to generate a Pages site. + +1. From the top navigation, click the **+** button and select **New project**. +1. Select **Create from Template**. +1. Next to one of the templates starting with **Pages**, click **Use template**. + +  + +1. Complete the form and click **Create project**. +1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** + and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your + site. + +The site can take approximately 30 minutes to deploy. +When the pipeline is finished, go to **Settings > Pages** to find the link to +your Pages website. + +For every change pushed to your repository, GitLab CI/CD runs a new pipeline +that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index c3e12026ca4..c5245c84dfb 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -47,7 +47,7 @@ To create a GitLab Pages website: | Document | Description | | -------- | ----------- | | [Fork a sample project](getting_started/fork_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | -| [Use a new project template](getting_started/pages_bundled_template.md) | Create a new project with Pages already configured by using a new project template. | +| [Use a new project template](getting_started/pages_new_project_template.md) | Create a new project with Pages already configured by using a new project template. | | [Use a `.gitlab-ci.yml` template](getting_started/new_or_existing_website.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. | | [Create a `gitlab-ci.yml` file from scratch](getting_started_part_four.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | |