diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2019-09-18 14:14:39 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2019-09-18 14:14:39 +0000 |
| commit | 1eb82b65c554f21d83447f895a6208905fabe112 (patch) | |
| tree | ab12f01b3dc46f11c02afea1e470a78f06ca70c2 /doc/user | |
| parent | 4ab54c2233e91f60a80e5b6fa2181e6899fdcc3e (diff) | |
| download | gitlab-ce-stable-branch-foss-test.tar.gz | |
Add latest changes from gitlab-org/gitlab@12-3-auto-deploy-20190916stable-branch-foss-test
Diffstat (limited to 'doc/user')
35 files changed, 953 insertions, 830 deletions
diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 7c24edb8558..c3f80c6a0fd 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -11,7 +11,7 @@ in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. If you are using [GitLab CI/CD](../../../ci/README.md), you can check your Docker images (or more precisely the containers) for known vulnerabilities by using -[Clair](https://github.com/coreos/clair) and [klar](https://github.com/optiopay/klar), +[Clair](https://github.com/coreos/clair) and [clair-scanner](https://github.com/arminc/clair-scanner), two open source tools for Vulnerability Static Analysis for containers. You can take advantage of Container Scanning by either [including the CI job](#configuration) in @@ -48,7 +48,7 @@ To enable Container Scanning in your pipeline, you need: running. If you're using the shared Runners on GitLab.com, this is already the case. - To [build and push](../../../ci/docker/using_docker_build.md#container-registry-examples) - your Docker image to your project's [Container Registry](../../packages/container_registry/index.md). + your Docker image to your project's [Container Registry](../../project/container_registry.md). The name of the Docker image should match the following scheme: ```text @@ -79,7 +79,7 @@ The included template will: 1. Create a `container_scanning` job in your CI/CD pipeline. 1. Pull the already built Docker image from your project's - [Container Registry](../../packages/container_registry/index.md) (see [requirements](#requirements)) + [Container Registry](../../project/container_registry.md) (see [requirements](#requirements)) and scan it for possible vulnerabilities. The results will be saved as a @@ -90,6 +90,10 @@ artifact available. Behind the scenes, the [GitLab Container Scanning analyzer](https://gitlab.com/gitlab-org/security-products/container-scanning) is used and runs the scans. +If you want to whitelist some specific vulnerabilities, you can do so by defining +them in a YAML file named `clair-whitelist.yml`. Read more in the +[Clair documentation](https://github.com/arminc/clair-scanner/blob/master/README.md#example-whitelist-yaml-file). + ## Example The following is a sample `.gitlab-ci.yml` that will build your Docker Image, push it to the container registry and run Container Scanning. @@ -120,31 +124,6 @@ build: - docker push $IMAGE ``` -## Vulnerability Whitelisting - -If you want to whitelist specific vulnerabilities, you'll need to: - - 1. Set `GIT_STRATEGY: fetch` in your `.gitlab-ci.yml` file by following the instructions described in the - [overriding the Container Scanning template](#overriding-the-container-scanning-template) section of this document. - 1. Define the whitelisted vulnerabilities in a YAML file named `clair-whitelist.yml` which must use the format described - in the [following whitelist example file](https://github.com/arminc/clair-scanner/blob/v12/example-whitelist.yaml). - 1. Add the `clair-whitelist.yml` file to the git repository of your project - -### Overriding the Container Scanning template - -If you want to override the job definition (for example, change properties like -`variables`), you need to declare a `container_scanning` job after the -template inclusion and specify any additional keys under it. For example: - -```yaml -include: - - template: Container-Scanning.gitlab-ci.yml - -container_scanning: - variables: - GIT_STRATEGY: fetch -``` - ## Security Dashboard The Security Dashboard is a good place to get an overview of all the security diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 5baaa92d3d8..166a71b6fbe 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -58,7 +58,7 @@ The following languages and dependency managers are supported. | JavaScript ([npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/en/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js) | | Go ([Golang](https://golang.org/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/7132 "Dependency Scanning for Go")) | not available | | PHP ([Composer](https://getcomposer.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| Python ([pip](https://pip.pypa.io/en/stable/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| Python ([pip](https://pip.pypa.io/en/stable/)) (only `requirements.txt` supported) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | Python ([Pipfile](https://docs.pipenv.org/en/latest/basics/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/11756 "Pipfile.lock support for Dependency Scanning"))| not available | | Python ([poetry](https://poetry.eustace.io/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/7006 "Support Poetry in Dependency Scanning")) | not available | | Ruby ([gem](https://rubygems.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) | diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 17d430cf1f2..197a1fc61c1 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -67,11 +67,6 @@ required to install all the other applications. It is installed in its own pod inside the cluster which can run the `helm` CLI in a safe environment. -NOTE: **Note:** -Installing Helm as a GitLab-managed App behind a proxy is not supported, -but a [workaround](../../topics/autodevops/index.md#installing-helm-behind-a-proxy) -is available. - ### Cert-Manager > Introduced in GitLab 11.6 for project- and group-level clusters. @@ -129,6 +124,34 @@ chart is used to install this application with a [`values.yaml`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/vendor/ingress/values.yaml) file. +#### Modsecurity Application Firewall + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/65192) in GitLab 12.3 (enabled using `ingress_modsecurity` [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-in-development)). + +GitLab supports +[`modsecurity`](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#modsecurity) +to check requests against [OWASP's Core Rule Set](https://www.modsecurity.org/CRS/Documentation/). +This feature: + +- Runs in "Detection-only mode" unless configured otherwise. +- Is viewable by checking your ingress controller's `modsec` log for rule violations. + For example: + + ```sh + kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- tail -f /var/log/modsec_audit.log + ``` + +There is a small performance overhead by enabling `modsecurity`. However, if this is +considered significant for your application, you can toggle the feature flag back to +false by running the following command within the Rails console: + +```ruby +Feature.disable(:ingress_modsecurity) +``` + +Once disabled, you must reinstall your ingress application for the changes to +take effect. + ### JupyterHub > - Introduced in GitLab 11.0 for project-level clusters. diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index d41f44f85cc..53229f5c286 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -137,6 +137,10 @@ The result will then be: - The Staging cluster will be used for the `deploy to staging` job. - The Production cluster will be used for the `deploy to production` job. +## Cluster environments **(PREMIUM)** + +Please see the documentation for [cluster environments](../../clusters/environments.md). + ## Security of Runners For important information about securely configuring GitLab Runners, see diff --git a/doc/user/group/dependency_proxy/index.md b/doc/user/group/dependency_proxy/index.md index f735ec0214f..771468fbba8 100644 --- a/doc/user/group/dependency_proxy/index.md +++ b/doc/user/group/dependency_proxy/index.md @@ -1,5 +1,74 @@ ---- -redirect_to: '../../packages/dependency_proxy/index.md' ---- +# Dependency Proxy **(PREMIUM)** -This document was moved to [another location](../../packages/dependency_proxy/index.md). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. + +NOTE: **Note:** +This is the user guide. In order to use the dependency proxy, an administrator +must first [configure it](../../../administration/dependency_proxy.md). + +For many organizations, it is desirable to have a local proxy for frequently used +upstream images/packages. In the case of CI/CD, the proxy is responsible for +receiving a request and returning the upstream image from a registry, acting +as a pull-through cache. + +The dependency proxy is available in the group level. To access it, navigate to +a group's **Overview > Dependency Proxy**. + + + +## Supported dependency proxies + +NOTE: **Note:** +For a list of the upcoming additions to the proxies, visit the +[direction page](https://about.gitlab.com/direction/package/dependency_proxy/#top-vision-items). + +The following dependency proxies are supported. + +| Dependency proxy | GitLab version | +| ---------------- | -------------- | +| Docker | 11.11+ | + +## Using the Docker dependency proxy + +With the Docker dependency proxy, you can use GitLab as a source for a Docker image. +To get a Docker image into the dependency proxy: + +1. Find the proxy URL on your group's page under **Overview > Dependency Proxy**, + for example `gitlab.com/groupname/dependency_proxy/containers`. +1. Trigger GitLab to pull the Docker image you want (e.g., `alpine:latest` or + `linuxserver/nextcloud:latest`) and store it in the proxy storage by using + one of the following ways: + + - Manually pulling the Docker image: + + ```bash + docker pull gitlab.com/groupname/dependency_proxy/containers/alpine:latest + ``` + + - From a `Dockerfile`: + + ```bash + FROM gitlab.com/groupname/dependency_proxy/containers/alpine:latest + ``` + + - In [`.gitlab-ci.yml`](../../../ci/yaml/README.md#image): + + ```bash + image: gitlab.com/groupname/dependency_proxy/containers/alpine:latest + ``` + +GitLab will then pull the Docker image from Docker Hub and will cache the blobs +on the GitLab server. The next time you pull the same image, it will get the latest +information about the image from Docker Hub but will serve the existing blobs +from GitLab. + +The blobs are kept forever, and there is no hard limit on how much data can be +stored. + +## Limitations + +The following limitations apply: + +- Only public groups are supported (authentication is not supported yet). +- Only Docker Hub is supported. +- This feature requires Docker Hub being available. diff --git a/doc/user/group/index.md b/doc/user/group/index.md index a0bdb737466..c09acd36e31 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -285,7 +285,7 @@ To change your group path: CAUTION: **Caution:** It is currently not possible to rename a namespace if it contains a -project with [Container Registry](../packages/container_registry/index.md) tags, +project with [Container Registry](../project/container_registry.md) tags, because the project cannot be moved. TIP: **TIP:** @@ -461,7 +461,7 @@ With [GitLab Issues Analytics](issues_analytics/index.md), you can see a bar cha ## Dependency Proxy **(PREMIUM)** -Use GitLab as a [dependency proxy](../packages/dependency_proxy/index.md) for upstream Docker images. +Use GitLab as a [dependency proxy](dependency_proxy/index.md) for upstream Docker images. <!-- ## Troubleshooting diff --git a/doc/user/index.md b/doc/user/index.md index e1833cab6b8..27e75189fc3 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -44,7 +44,7 @@ GitLab is a Git-based platform that integrates a great number of essential tools branch with [Review Apps](../ci/review_apps/index.md). - Building, testing, and deploying with built-in [Continuous Integration](../ci/README.md). - Deploying personal and professional static websites with [GitLab Pages](project/pages/index.md). -- Integrating with Docker by using [GitLab Container Registry](packages/container_registry/index.md). +- Integrating with Docker by using [GitLab Container Registry](project/container_registry.md). - Tracking the development lifecycle by using [GitLab Cycle Analytics](project/cycle_analytics.md). With GitLab Enterprise Edition, you can also: @@ -92,7 +92,7 @@ directly from GitLab. No third-party integrations needed. - [Review Apps](../ci/review_apps/index.md): Live-preview the changes introduced by a merge request with Review Apps. - [GitLab Pages](project/pages/index.md): Publish your static site directly from GitLab with GitLab Pages. You can build, test, and deploy any Static Site Generator with Pages. -- [GitLab Container Registry](packages/container_registry/index.md): Build and deploy Docker +- [GitLab Container Registry](project/container_registry.md): Build and deploy Docker images with Container Registry. ## Account diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md deleted file mode 100644 index 710e7bd405b..00000000000 --- a/doc/user/packages/container_registry/index.md +++ /dev/null @@ -1,158 +0,0 @@ -# GitLab Container Registry - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4040) in GitLab 8.8. -> - Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker -> versions earlier than 1.10. -> - Starting from GitLab 8.12, if you have 2FA enabled in your account, you need -> to pass a [personal access token](../../profile/personal_access_tokens.md) instead of your password in order to -> login to GitLab's Container Registry. -> - Multiple level image names support was added in GitLab 9.1. - -NOTE: **Note:** -This document is the user guide. To learn how to enable GitLab Container -Registry across your GitLab instance, visit the -[administrator documentation](../../../administration/packages/container_registry.md). - -With the Docker Container Registry integrated into GitLab, every project can -have its own space to store its Docker images. - -You can read more about Docker Registry at <https://docs.docker.com/registry/introduction/>. - -## Enable the Container Registry for your project - -If you cannot find the **Packages > Container Registry** entry under your -project's sidebar, it is not enabled in your GitLab instance. Ask your -administrator to enable GitLab Container Registry following the -[administration documentation](../../../administration/packages/container_registry.md). - -If you are using GitLab.com, this is enabled by default so you can start using -the Registry immediately. Currently there is a soft (10GB) size restriction for -Registry on GitLab.com, as part of the [repository size limit](../../project/repository/index.md). - -Once enabled for your GitLab instance, to enable Container Registry for your -project: - -1. Go to your project's **Settings > General** page. -1. Expand the **Visibility, project features, permissions** section - and enable the **Container Registry** feature on your project. For new - projects this might be enabled by default. For existing projects - (prior GitLab 8.8), you will have to explicitly enable it. -1. Press **Save changes** for the changes to take effect. You should now be able - to see the **Packages > Container Registry** link in the sidebar. - -## Build and push images - -> **Notes:** -> -> - Moving or renaming existing container registry repositories is not supported -> once you have pushed images because the images are signed, and the -> signature includes the repository name. -> - To move or rename a repository with a container registry you will have to -> delete all existing images. - -If you visit the **Packages > Container Registry** link under your project's -menu, you can see the explicit instructions to login to the Container Registry -using your GitLab credentials. - -For example if the Registry's URL is `registry.example.com`, then you should be -able to login with: - -```sh -docker login registry.example.com -``` - -Building and publishing images should be a straightforward process. Just make -sure that you are using the Registry URL with the namespace and project name -that is hosted on GitLab: - -```sh -docker build -t registry.example.com/group/project/image . -docker push registry.example.com/group/project/image -``` - -Your image will be named after the following scheme: - -```text -<registry URL>/<namespace>/<project>/<image> -``` - -GitLab supports up to three levels of image repository names. - -Following examples of image tags are valid: - -```text -registry.example.com/group/project:some-tag -registry.example.com/group/project/image:latest -registry.example.com/group/project/my/image:rc1 -``` - -## Use images from GitLab Container Registry - -To download and run a container from images hosted in GitLab Container Registry, -use `docker run`: - -```sh -docker run [options] registry.example.com/group/project/image [arguments] -``` - -For more information on running Docker containers, visit the -[Docker documentation](https://docs.docker.com/engine/userguide/intro/). - -## Control Container Registry from within GitLab - -GitLab offers a simple Container Registry management panel. Go to your project -and click **Packages > Container Registry** in the project menu. - -This view will show you all tags in your project and will easily allow you to -delete them. - -## Build and push images using GitLab CI - -NOTE: **Note:** -This feature requires GitLab 8.8 and GitLab Runner 1.2. - -Make sure that your GitLab Runner is configured to allow building Docker images by -following the [Using Docker Build](../../../ci/docker/using_docker_build.md) -and [Using the GitLab Container Registry documentation](../../../ci/docker/using_docker_build.md#using-the-gitlab-container-registry). -Alternatively, you can [build images with Kaniko](../../../ci/docker/using_kaniko.md) if the Docker builds are not an option for you. - -## Using with private projects - -> Personal Access tokens were [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845) in GitLab 9.3. -> Project Deploy Tokens were [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17894) in GitLab 10.7 - -If a project is private, credentials will need to be provided for authorization. -There are two ways to do this: - -- By using a [personal access token](../../profile/personal_access_tokens.md). -- By using a [deploy token](../../project/deploy_tokens/index.md). - -The minimal scope needed for both of them is `read_registry`. - -Example of using a token: - -```sh -docker login registry.example.com -u <username> -p <token> -``` - -## Troubleshooting the GitLab Container Registry - -### Docker connection error - -A Docker connection error can occur when there are special characters in either the group, -project or branch name. Special characters can include: - -- Leading underscore -- Trailing hyphen/dash -- Double hyphen/dash - -To get around this, you can [change the group path](../../group/index.md#changing-a-groups-path), -[change the project path](../../project/settings/index.md#renaming-a-repository) or change the branch -name. - -### Troubleshoot as a GitLab server admin - -Troubleshooting the GitLab Container Registry, most of the times, requires -administration access to the GitLab server. - -[Read how to troubleshoot the Container Registry](../../../administration/packages/container_registry.md#troubleshooting). diff --git a/doc/user/packages/dependency_proxy/img/group_dependency_proxy.png b/doc/user/packages/dependency_proxy/img/group_dependency_proxy.png Binary files differdeleted file mode 100644 index 035aff0b6c4..00000000000 --- a/doc/user/packages/dependency_proxy/img/group_dependency_proxy.png +++ /dev/null diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md deleted file mode 100644 index 8c337f74dcf..00000000000 --- a/doc/user/packages/dependency_proxy/index.md +++ /dev/null @@ -1,74 +0,0 @@ -# Dependency Proxy **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. - -NOTE: **Note:** -This is the user guide. In order to use the dependency proxy, an administrator -must first [configure it](../../../administration/packages/dependency_proxy.md). - -For many organizations, it is desirable to have a local proxy for frequently used -upstream images/packages. In the case of CI/CD, the proxy is responsible for -receiving a request and returning the upstream image from a registry, acting -as a pull-through cache. - -The dependency proxy is available in the group level. To access it, navigate to -a group's **Overview > Dependency Proxy**. - - - -## Supported dependency proxies - -NOTE: **Note:** -For a list of the upcoming additions to the proxies, visit the -[direction page](https://about.gitlab.com/direction/package/dependency_proxy/#top-vision-items). - -The following dependency proxies are supported. - -| Dependency proxy | GitLab version | -| ---------------- | -------------- | -| Docker | 11.11+ | - -## Using the Docker dependency proxy - -With the Docker dependency proxy, you can use GitLab as a source for a Docker image. -To get a Docker image into the dependency proxy: - -1. Find the proxy URL on your group's page under **Overview > Dependency Proxy**, - for example `gitlab.com/groupname/dependency_proxy/containers`. -1. Trigger GitLab to pull the Docker image you want (e.g., `alpine:latest` or - `linuxserver/nextcloud:latest`) and store it in the proxy storage by using - one of the following ways: - - - Manually pulling the Docker image: - - ```bash - docker pull gitlab.com/groupname/dependency_proxy/containers/alpine:latest - ``` - - - From a `Dockerfile`: - - ```bash - FROM gitlab.com/groupname/dependency_proxy/containers/alpine:latest - ``` - - - In [`.gitlab-ci.yml`](../../../ci/yaml/README.md#image): - - ```bash - image: gitlab.com/groupname/dependency_proxy/containers/alpine:latest - ``` - -GitLab will then pull the Docker image from Docker Hub and will cache the blobs -on the GitLab server. The next time you pull the same image, it will get the latest -information about the image from Docker Hub but will serve the existing blobs -from GitLab. - -The blobs are kept forever, and there is no hard limit on how much data can be -stored. - -## Limitations - -The following limitations apply: - -- Only public groups are supported (authentication is not supported yet). -- Only Docker Hub is supported. -- This feature requires Docker Hub being available. diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md deleted file mode 100644 index 506eb5703a6..00000000000 --- a/doc/user/packages/index.md +++ /dev/null @@ -1,19 +0,0 @@ -# GitLab Package Registry - -GitLab Packages allows organizations to utilize GitLab as a private repository -for a variety of common package managers. Users are able to build and publish -packages, which can be easily consumed as a dependency in downstream projects. - -The Packages feature allows GitLab to act as a repository for the following: - -| Software repository | Description | Available in GitLab version | -| ------------------- | ----------- | --------------------------- | -| [Container Registry](container_registry/index.md) | The GitLab Container Registry enables every project in GitLab to have its own space to store [Docker](https://www.docker.com/) images. | 8.8+ | -| [Dependency Proxy](dependency_proxy/index.md) **(PREMIUM)** | The GitLab Dependency Proxy sets up a local proxy for frequently used upstream images/packages. | 11.11+ | -| [Maven Repository](maven_repository/index.md) **(PREMIUM)** | The GitLab Maven Repository enables every project in GitLab to have its own space to store [Maven](https://maven.apache.org/) packages. | 11.3+ | -| [NPM Registry](npm_registry/index.md) **(PREMIUM)** | The GitLab NPM Registry enables every project in GitLab to have its own space to store [NPM](https://www.npmjs.com/) packages. | 11.7+ | - -TIP: **Tip:** -Don't you see your package management system supported yet? Consider contributing -to GitLab. This [development documentation](../../development/packages.md) will -guide you through the process. diff --git a/doc/user/packages/maven_repository/img/maven_package_view.png b/doc/user/packages/maven_repository/img/maven_package_view.png Binary files differdeleted file mode 100644 index 2eb4b6f76b4..00000000000 --- a/doc/user/packages/maven_repository/img/maven_package_view.png +++ /dev/null diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md deleted file mode 100644 index 2c400653fcc..00000000000 --- a/doc/user/packages/maven_repository/index.md +++ /dev/null @@ -1,340 +0,0 @@ -# GitLab Maven Repository **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5811) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. - -With the GitLab [Maven](https://maven.apache.org) Repository, every -project can have its own space to store its Maven artifacts. - - - -## Enabling the Maven Repository - -NOTE: **Note:** -This option is available only if your GitLab administrator has -[enabled support for the Maven repository](../../../administration/packages/index.md).**(PREMIUM ONLY)** - -After the Packages feature is enabled, the Maven Repository will be available for -all new projects by default. To enable it for existing projects, or if you want -to disable it: - -1. Navigate to your project's **Settings > General > Permissions**. -1. Find the Packages feature and enable or disable it. -1. Click on **Save changes** for the changes to take effect. - -You should then be able to see the **Packages** section on the left sidebar. -Next, you must configure your project to authorize with the GitLab Maven -repository. - -## Authenticating to the GitLab Maven Repository - -If a project is private or you want to upload Maven artifacts to GitLab, -credentials will need to be provided for authorization. Support is available for -[personal access tokens](#authenticating-with-a-personal-access-token) and -[CI job tokens](#authenticating-with-a-ci-job-token) only. -[Deploy tokens](../../project/deploy_tokens/index.md) and regular username/password -credentials do not work. - -### Authenticating with a personal access token - -To authenticate with a [personal access token](../../profile/personal_access_tokens.md), -add a corresponding section to your -[`settings.xml`](https://maven.apache.org/settings.html) file: - -```xml -<settings> - <servers> - <server> - <id>gitlab-maven</id> - <configuration> - <httpHeaders> - <property> - <name>Private-Token</name> - <value>REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN</value> - </property> - </httpHeaders> - </configuration> - </server> - </servers> -</settings> -``` - -You should now be able to upload Maven artifacts to your project. - -### Authenticating with a CI job token - -If you're using Maven with GitLab CI/CD, a CI job token can be used instead -of a personal access token. - -To authenticate with a CI job token, add a corresponding section to your -[`settings.xml`](https://maven.apache.org/settings.html) file: - -```xml -<settings> - <servers> - <server> - <id>gitlab-maven</id> - <configuration> - <httpHeaders> - <property> - <name>Job-Token</name> - <value>${env.CI_JOB_TOKEN}</value> - </property> - </httpHeaders> - </configuration> - </server> - </servers> -</settings> -``` - -You can read more on -[how to create Maven packages using GitLab CI/CD](#creating-maven-packages-with-gitlab-cicd). - -## Configuring your project to use the GitLab Maven repository URL - -To download and upload packages from GitLab, you need a `repository` and -`distributionManagement` section in your `pom.xml` file. - -Depending on your workflow and the amount of Maven packages you have, there are -3 ways you can configure your project to use the GitLab endpoint for Maven packages: - -- **Project level**: Useful when you have few Maven packages which are not under - the same GitLab group. -- **Group level**: Useful when you have many Maven packages under the same GitLab - group. -- **Instance level**: Useful when you have many Maven packages under different - GitLab groups or on their own namespace. - -NOTE: **Note:** -In all cases, you need a project specific URL for uploading a package in -the `distributionManagement` section. - -### Project level Maven endpoint - -The example below shows how the relevant `repository` section of your `pom.xml` -would look like: - -```xml -<repositories> - <repository> - <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> - </repository> -</repositories> -<distributionManagement> - <repository> - <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> - </repository> - <snapshotRepository> - <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> - </snapshotRepository> -</distributionManagement> -``` - -The `id` must be the same with what you -[defined in `settings.xml`](#authenticating-to-the-gitlab-maven-repository). - -Replace `PROJECT_ID` with your project ID which can be found on the home page -of your project. - -If you have a self-hosted GitLab installation, replace `gitlab.com` with your -domain name. - -NOTE: **Note:** -For retrieving artifacts, you can use either the -[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the project -(e.g., `group%2Fproject`) or the project's ID (e.g., `42`). However, only the -project's ID can be used for uploading. - -### Group level Maven endpoint - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/8798) in GitLab Premium 11.7. - -If you rely on many packages, it might be inefficient to include the `repository` section -with a unique URL for each package. Instead, you can use the group level endpoint for -all your Maven packages stored within one GitLab group. Only packages you have access to -will be available for download. - -The group level endpoint works with any package names, which means the you -have the flexibility of naming compared to [instance level endpoint](#instance-level-maven-endpoint). -However, GitLab will not guarantee the uniqueness of the package names within -the group. You can have two projects with the same package name and package -version. As a result, GitLab will serve whichever one is more recent. - -The example below shows how the relevant `repository` section of your `pom.xml` -would look like. You still need a project specific URL for uploading a package in -the `distributionManagement` section: - -```xml -<repositories> - <repository> - <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/groups/my-group/-/packages/maven</url> - </repository> -</repositories> -<distributionManagement> - <repository> - <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> - </repository> - <snapshotRepository> - <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> - </snapshotRepository> -</distributionManagement> -``` - -The `id` must be the same with what you -[defined in `settings.xml`](#authenticating-to-the-gitlab-maven-repository). - -Replace `my-group` with your group name and `PROJECT_ID` with your project ID -which can be found on the home page of your project. - -If you have a self-hosted GitLab installation, replace `gitlab.com` with your -domain name. - -NOTE: **Note:** -For retrieving artifacts, you can use either the -[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the group -(e.g., `group%2Fsubgroup`) or the group's ID (e.g., `12`). - -### Instance level Maven endpoint - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/8274) in GitLab Premium 11.7. - -If you rely on many packages, it might be inefficient to include the `repository` section -with a unique URL for each package. Instead, you can use the instance level endpoint for -all maven packages stored in GitLab and the packages you have access to will be available -for download. - -Note that **only packages that have the same path as the project** are exposed via -the instance level endpoint. - -| Project | Package | Instance level endpoint available | -| ------- | ------- | --------------------------------- | -| `foo/bar` | `foo/bar/1.0-SNAPSHOT` | Yes | -| `gitlab-org/gitlab-ce` | `foo/bar/1.0-SNAPSHOT` | No | -| `gitlab-org/gitlab-ce` | `gitlab-org/gitlab-ce/1.0-SNAPSHOT` | Yes | - -The example below shows how the relevant `repository` section of your `pom.xml` -would look like. You still need a project specific URL for uploading a package in -the `distributionManagement` section: - -```xml -<repositories> - <repository> - <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/packages/maven</url> - </repository> -</repositories> -<distributionManagement> - <repository> - <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> - </repository> - <snapshotRepository> - <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> - </snapshotRepository> -</distributionManagement> -``` - -The `id` must be the same with what you -[defined in `settings.xml`](#authenticating-to-the-gitlab-maven-repository). - -Replace `PROJECT_ID` with your project ID which can be found on the home page -of your project. - -If you have a self-hosted GitLab installation, replace `gitlab.com` with your -domain name. - -NOTE: **Note:** -For retrieving artifacts, you can use either the -[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the project -(e.g., `group%2Fproject`) or the project's ID (e.g., `42`). However, only the -project's ID can be used for uploading. - -## Uploading packages - -Once you have set up the [authentication](#authenticating-to-the-gitlab-maven-repository) -and [configuration](#configuring-your-project-to-use-the-gitlab-maven-repository-url), -test to upload a Maven artifact from a project of yours: - -```sh -mvn deploy -``` - -You can then navigate to your project's **Packages** page and see the uploaded -artifacts or even delete them. - -## Creating Maven packages with GitLab CI/CD - -Once you have your repository configured to use the GitLab Maven Repository, -you can configure GitLab CI/CD to build new packages automatically. The example below -shows how to create a new package each time the `master` branch is updated: - -1. Create a `ci_settings.xml` file that will serve as Maven's `settings.xml` file. - Add the server section with the same id you defined in your `pom.xml` file. - For example, in our case it's `gitlab-maven`: - - ```xml - <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"> - <servers> - <server> - <id>gitlab-maven</id> - <configuration> - <httpHeaders> - <property> - <name>Job-Token</name> - <value>${env.CI_JOB_TOKEN}</value> - </property> - </httpHeaders> - </configuration> - </server> - </servers> - </settings> - ``` - -1. Make sure your `pom.xml` file includes the following: - - ```xml - <repositories> - <repository> - <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> - </repository> - </repositories> - <distributionManagement> - <repository> - <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> - </repository> - <snapshotRepository> - <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> - </snapshotRepository> - </distributionManagement> - ``` - - TIP: **Tip:** - You can either let Maven utilize the CI environment variables or hardcode your project's ID. - -1. Add a `deploy` job to your `.gitlab-ci.yml` file: - - ```yaml - deploy: - image: maven:3.3.9-jdk-8 - script: - - 'mvn deploy -s ci_settings.xml' - only: - - master - ``` - -1. Push those files to your repository. - -The next time the `deploy` job runs, it will copy `ci_settings.xml` to the -user's home location (in this case the user is `root` since it runs in a -Docker container), and Maven will utilize the configured CI -[environment variables](../../../ci/variables/README.md#predefined-environment-variables). diff --git a/doc/user/packages/npm_registry/img/npm_package_view.png b/doc/user/packages/npm_registry/img/npm_package_view.png Binary files differdeleted file mode 100644 index e0634718c02..00000000000 --- a/doc/user/packages/npm_registry/img/npm_package_view.png +++ /dev/null diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md deleted file mode 100644 index 30de301b96a..00000000000 --- a/doc/user/packages/npm_registry/index.md +++ /dev/null @@ -1,147 +0,0 @@ -# GitLab NPM Registry **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. - -With the GitLab NPM Registry, every -project can have its own space to store NPM packages. - - - -NOTE: **Note:** -Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported. - -## Enabling the NPM Registry - -NOTE: **Note:** -This option is available only if your GitLab administrator has -[enabled support for the NPM registry](../../../administration/packages/index.md).**(PREMIUM ONLY)** - -After the NPM registry is enabled, it will be available for all new projects -by default. To enable it for existing projects, or if you want to disable it: - -1. Navigate to your project's **Settings > General > Permissions**. -1. Find the Packages feature and enable or disable it. -1. Click on **Save changes** for the changes to take effect. - -You should then be able to see the **Packages** section on the left sidebar. - -Before proceeding to authenticating with the GitLab NPM Registry, you should -get familiar with the package naming convention. - -## Package naming convention - -**Packages must be scoped in the root namespace of the project**. The package -name may be anything but it is preferred that the project name be used unless -it is not possible due to a naming collision. For example: - -| Project | Package | Supported | -| ---------------------- | ----------------------- | --------- | -| `foo/bar` | `@foo/bar` | Yes | -| `foo/bar/baz` | `@foo/baz` | Yes | -| `foo/bar/buz` | `@foo/anything` | Yes | -| `gitlab-org/gitlab-ce` | `@gitlab-org/gitlab-ce` | Yes | -| `gitlab-org/gitlab-ce` | `@foo/bar` | No | - -Now, you can configure your project to authenticate with the GitLab NPM -Registry. - -## Authenticating to the GitLab NPM Registry - -If a project is private or you want to upload an NPM package to GitLab, -credentials will need to be provided for authentication. Support is available for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow) or [personal access tokens](../../profile/personal_access_tokens.md). - -CAUTION: **2FA is only supported with personal access tokens:** -If you have 2FA enabled, you need to use a [personal access token](../../profile/personal_access_tokens.md) with OAuth headers. Standard OAuth tokens won't be able to authenticate to the GitLab NPM Registry. - -### Authenticating with an OAuth token - -To authenticate with an [OAuth token](../../../api/oauth2.md#resource-owner-password-credentials-flow) -or [personal access token](../../profile/personal_access_tokens.md), add a corresponding section to your `.npmrc` file: - -```ini -; Set URL for your scoped packages. -; For example package with name `@foo/bar` will use this URL for download -@foo:registry=https://gitlab.com/api/v4/packages/npm/ - -; Add the token for the scoped packages URL. This will allow you to download -; `@foo/` packages from private projects. -//gitlab.com/api/v4/packages/npm/:_authToken=<your_token> - -; Add token for uploading to the registry. Replace <your_project_id> -; with the project you want your package to be uploaded to. -//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_token> -``` - -Replace `<your_project_id>` with your project ID which can be found on the home page -of your project and `<your_token>` with your OAuth or personal access token. - -If you have a self-hosted GitLab installation, replace `gitlab.com` with your -domain name. - -You should now be able to download and upload NPM packages to your project. - -NOTE: **Note:** -If you encounter an error message with [Yarn](https://yarnpkg.com/en/), see the -[troubleshooting section](#troubleshooting). - -## Uploading packages - -Before you will be able to upload a package, you need to specify the registry -for NPM. To do this, add the following section to the bottom of `package.json`: - -```json - "publishConfig": { - "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/" - } -``` - -Replace `<your_project_id>` with your project ID, which can be found on the home -page of your project, and replace `@foo` with your own scope. - -If you have a self-hosted GitLab installation, replace `gitlab.com` with your -domain name. - -Once you have enabled it and set up [authentication](#authenticating-to-the-gitlab-npm-registry), -you can upload an NPM package to your project: - -```sh -npm publish -``` - -You can then navigate to your project's **Packages** page and see the uploaded -packages or even delete them. - -If you attempt to publish a package with a name that already exists within -a given scope, you will receive a `403 Forbidden!` error. - -## Uploading a package with the same version twice - -If you upload a package with a same name and version twice, GitLab will show -both packages in the UI, but the GitLab NPM Registry will expose the most recent -one as it supports only one package per version for `npm install`. - -## Troubleshooting - -### Error running yarn with NPM registry - -If you are using [yarn](https://yarnpkg.com/en/) with the NPM registry, you may get -an error message like: - -```sh -yarn install v1.15.2 -warning package.json: No license field -info No lockfile found. -warning XXX: No license field -[1/4] 🔍 Resolving packages... -[2/4] 🚚 Fetching packages... -error An unexpected error occurred: "https://gitlab.com/api/v4/projects/XXX/packages/npm/XXX/XXX/-/XXX/XXX-X.X.X.tgz: Request failed \"404 Not Found\"". -info If you think this is a bug, please open a bug report with the information provided in "/Users/XXX/gitlab-migration/module-util/yarn-error.log". -info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command -``` - -In this case, try adding this to your `.npmrc` file (and replace `<your_oauth_token>` -with your with your OAuth or personal access token): - -```text -//gitlab.com/api/v4/projects/:_authToken=<your_oauth_token> -``` diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 8232ae44c68..46a3090e268 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -76,8 +76,8 @@ The following table depicts the various user permission levels in a project. | See a list of merge requests | | ✓ | ✓ | ✓ | ✓ | | View project statistics | | ✓ | ✓ | ✓ | ✓ | | View Error Tracking list | | ✓ | ✓ | ✓ | ✓ | -| Pull from [Maven repository](packages/maven_repository/index.md) or [NPM registry](packages/npm_registry/index.md) **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | -| Publish to [Maven repository](packages/maven_repository/index.md) or [NPM registry](packages/npm_registry/index.md) **(PREMIUM)** | | | ✓ | ✓ | ✓ | +| Pull from [Maven repository](project/packages/maven_repository.md) or [NPM registry](project/packages/npm_registry.md) **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | +| Publish to [Maven repository](project/packages/maven_repository.md) or [NPM registry](project/packages/npm_registry.md) **(PREMIUM)** | | | ✓ | ✓ | ✓ | | Upload [Design Management](project/issues/design_management.md) files **(PREMIUM)** | | | ✓ | ✓ | ✓ | | Create new branches | | | ✓ | ✓ | ✓ | | Push to non-protected branches | | | ✓ | ✓ | ✓ | diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index d9144f9b5fd..40b7294c3bb 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -75,7 +75,7 @@ To change your `username`: CAUTION: **Caution:** It is currently not possible to change your username if it contains a -project with [Container Registry](../packages/container_registry/index.md) tags, +project with [Container Registry](../project/container_registry.md) tags, because the project cannot be moved. TIP: **Tip:** diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index ffe6104698f..d556daa3460 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -53,7 +53,7 @@ the following table. [2fa]: ../account/two_factor_authentication.md [api]: ../../api/README.md [ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749 -[container registry]: ../packages/container_registry/index.md +[container registry]: ../project/container_registry.md [users]: ../../api/users.md [usage]: ../../api/README.md#personal-access-tokens diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index 91c9d3171dc..c9eb81b990c 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -1,5 +1,317 @@ ---- -redirect_to: '../packages/container_registry/index.md' ---- +# GitLab Container Registry -This document was moved to [another location](../packages/container_registry/index.md). +> - [Introduced][ce-4040] in GitLab 8.8. +> - Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker +> versions earlier than 1.10. +> - Starting from GitLab 8.12, if you have 2FA enabled in your account, you need +> to pass a [personal access token][pat] instead of your password in order to +> login to GitLab's Container Registry. +> - Multiple level image names support was added in GitLab 9.1. + +With the Docker Container Registry integrated into GitLab, every project can +have its own space to store its Docker images. + +This document is the user guide. To learn how to enable GitLab Container +Registry across your GitLab instance, visit the +[administrator documentation](../../administration/container_registry.md). + +You can read more about Docker Registry at <https://docs.docker.com/registry/introduction/>. + +## Enable the Container Registry for your project + +If you cannot find the **Packages > Container Registry** entry under your +project's sidebar, it is not enabled in your GitLab instance. Ask your +administrator to enable GitLab Container Registry following the +[administration documentation](../../administration/container_registry.md). + +If you are using GitLab.com, this is enabled by default so you can start using +the Registry immediately. Currently there is a soft (10GB) size restriction for +registry on GitLab.com, as part of the [repository size limit](repository/index.md). + +Once enabled for your GitLab instance, to enable Container Registry for your +project: + +1. Go to your project's **Settings > General** page. +1. Expand the **Visibility, project features, permissions** section + and enable the **Container Registry** feature on your project. For new + projects this might be enabled by default. For existing projects + (prior GitLab 8.8), you will have to explicitly enable it. +1. Press **Save changes** for the changes to take effect. You should now be able + to see the **Packages > Container Registry** link in the sidebar. + +## Build and push images + +> **Notes:** +> +> - Moving or renaming existing container registry repositories is not supported +> once you have pushed images because the images are signed, and the +> signature includes the repository name. +> - To move or rename a repository with a container registry you will have to +> delete all existing images. + +If you visit the **Packages > Container Registry** link under your project's +menu, you can see the explicit instructions to login to the Container Registry +using your GitLab credentials. + +For example if the Registry's URL is `registry.example.com`, then you should be +able to login with: + +```sh +docker login registry.example.com +``` + +Building and publishing images should be a straightforward process. Just make +sure that you are using the Registry URL with the namespace and project name +that is hosted on GitLab: + +```sh +docker build -t registry.example.com/group/project/image . +docker push registry.example.com/group/project/image +``` + +Your image will be named after the following scheme: + +```text +<registry URL>/<namespace>/<project>/<image> +``` + +GitLab supports up to three levels of image repository names. + +Following examples of image tags are valid: + +```text +registry.example.com/group/project:some-tag +registry.example.com/group/project/image:latest +registry.example.com/group/project/my/image:rc1 +``` + +## Use images from GitLab Container Registry + +To download and run a container from images hosted in GitLab Container Registry, +use `docker run`: + +```sh +docker run [options] registry.example.com/group/project/image [arguments] +``` + +For more information on running Docker containers, visit the +[Docker documentation][docker-docs]. + +## Control Container Registry from within GitLab + +GitLab offers a simple Container Registry management panel. Go to your project +and click **Packages > Container Registry** in the project menu. + +This view will show you all tags in your project and will easily allow you to +delete them. + +## Build and push images using GitLab CI + +> **Note:** +This feature requires GitLab 8.8 and GitLab Runner 1.2. + +Make sure that your GitLab Runner is configured to allow building Docker images by +following the [Using Docker Build](../../ci/docker/using_docker_build.md) +and [Using the GitLab Container Registry documentation](../../ci/docker/using_docker_build.md#using-the-gitlab-container-registry). +Alternatively, you can [build images with Kaniko](../../ci/docker/using_kaniko.md) if the Docker builds are not an option for you. + +## Using with private projects + +> Personal Access tokens were [introduced][ce-11845] in GitLab 9.3. +> Project Deploy Tokens were [introduced][ce-17894] in GitLab 10.7 + +If a project is private, credentials will need to be provided for authorization. +There are two ways to do this: + +- By using a [personal access token](../profile/personal_access_tokens.md). +- By using a [deploy token](../project/deploy_tokens/index.md). + +The minimal scope needed for both of them is `read_registry`. + +Example of using a token: + +```sh +docker login registry.example.com -u <username> -p <token> +``` + +## Troubleshooting the GitLab Container Registry + +### Basic Troubleshooting + +1. Check to make sure that the system clock on your Docker client and GitLab server have + been synchronized (e.g. via NTP). + +1. If you are using an S3-backed Registry, double check that the IAM + permissions and the S3 credentials (including region) are correct. See [the + sample IAM policy](https://docs.docker.com/registry/storage-drivers/s3/) + for more details. + +1. Check the Registry logs (e.g. `/var/log/gitlab/registry/current`) and the GitLab production logs + for errors (e.g. `/var/log/gitlab/gitlab-rails/production.log`). You may be able to find clues + there. + +#### Enable the registry debug server + +The optional debug server can be enabled by setting the registry debug address +in your `gitlab.rb` configuration. + +```ruby +registry['debug_addr'] = "localhost:5001" +``` + +After adding the setting, [reconfigure] GitLab to apply the change. + +Use curl to request debug output from the debug server: + +```bash +curl localhost:5001/debug/health +curl localhost:5001/debug/vars +``` + +#### Docker connection error + +A Docker connection error can occur when there are special characters in either the group, +project or branch name. Special characters can include: + +- Leading underscore +- Trailing hyphen/dash +- Double hyphen/dash + +To get around this, you can [change the group path](../group/index.md#changing-a-groups-path), +[change the project path](../project/settings/index.md#renaming-a-repository) or chanage the branch +name. + +### Advanced Troubleshooting + +NOTE: **Note:** +The following section is only recommended for experts. + +Sometimes it's not obvious what is wrong, and you may need to dive deeper into +the communication between the Docker client and the Registry to find out +what's wrong. We will use a concrete example in the past to illustrate how to +diagnose a problem with the S3 setup. + +#### Unexpected 403 error during push + +A user attempted to enable an S3-backed Registry. The `docker login` step went +fine. However, when pushing an image, the output showed: + +```text +The push refers to a repository [s3-testing.myregistry.com:4567/root/docker-test/docker-image] +dc5e59c14160: Pushing [==================================================>] 14.85 kB +03c20c1a019a: Pushing [==================================================>] 2.048 kB +a08f14ef632e: Pushing [==================================================>] 2.048 kB +228950524c88: Pushing 2.048 kB +6a8ecde4cc03: Pushing [==> ] 9.901 MB/205.7 MB +5f70bf18a086: Pushing 1.024 kB +737f40e80b7f: Waiting +82b57dbc5385: Waiting +19429b698a22: Waiting +9436069b92a3: Waiting +error parsing HTTP 403 response body: unexpected end of JSON input: "" +``` + +This error is ambiguous, as it's not clear whether the 403 is coming from the +GitLab Rails application, the Docker Registry, or something else. In this +case, since we know that since the login succeeded, we probably need to look +at the communication between the client and the Registry. + +The REST API between the Docker client and Registry is [described +here](https://docs.docker.com/registry/spec/api/). Normally, one would just +use Wireshark or tcpdump to capture the traffic and see where things went +wrong. However, since all communications between Docker clients and servers +are done over HTTPS, it's a bit difficult to decrypt the traffic quickly even +if you know the private key. What can we do instead? + +One way would be to disable HTTPS by setting up an [insecure +Registry](https://docs.docker.com/registry/insecure/). This could introduce a +security hole and is only recommended for local testing. If you have a +production system and can't or don't want to do this, there is another way: +use mitmproxy, which stands for Man-in-the-Middle Proxy. + +#### mitmproxy + +[mitmproxy](https://mitmproxy.org/) allows you to place a proxy between your +client and server to inspect all traffic. One wrinkle is that your system +needs to trust the mitmproxy SSL certificates for this to work. + +The following installation instructions assume you are running Ubuntu: + +1. [Install mitmproxy](https://docs.mitmproxy.org/stable/overview-installation/). +1. Run `mitmproxy --port 9000` to generate its certificates. + Enter <kbd>CTRL</kbd>-<kbd>C</kbd> to quit. +1. Install the certificate from `~/.mitmproxy` to your system: + + ```sh + sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt + sudo update-ca-certificates + ``` + +If successful, the output should indicate that a certificate was added: + +```sh +Updating certificates in /etc/ssl/certs... 1 added, 0 removed; done. +Running hooks in /etc/ca-certificates/update.d....done. +``` + +To verify that the certificates are properly installed, run: + +```sh +mitmproxy --port 9000 +``` + +This will run mitmproxy on port `9000`. In another window, run: + +```sh +curl --proxy http://localhost:9000 https://httpbin.org/status/200 +``` + +If everything is set up correctly, you will see information on the mitmproxy window and +no errors from the curl commands. + +#### Running the Docker daemon with a proxy + +For Docker to connect through a proxy, you must start the Docker daemon with the +proper environment variables. The easiest way is to shutdown Docker (e.g. `sudo initctl stop docker`) +and then run Docker by hand. As root, run: + +```sh +export HTTP_PROXY="http://localhost:9000" +export HTTPS_PROXY="https://localhost:9000" +docker daemon --debug +``` + +This will launch the Docker daemon and proxy all connections through mitmproxy. + +#### Running the Docker client + +Now that we have mitmproxy and Docker running, we can attempt to login and push +a container image. You may need to run as root to do this. For example: + +```sh +docker login s3-testing.myregistry.com:4567 +docker push s3-testing.myregistry.com:4567/root/docker-test/docker-image +``` + +In the example above, we see the following trace on the mitmproxy window: + + + +The above image shows: + +- The initial PUT requests went through fine with a 201 status code. +- The 201 redirected the client to the S3 bucket. +- The HEAD request to the AWS bucket reported a 403 Unauthorized. + +What does this mean? This strongly suggests that the S3 user does not have the right +[permissions to perform a HEAD request](http://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectHEAD.html). +The solution: check the [IAM permissions again](https://docs.docker.com/registry/storage-drivers/s3/). +Once the right permissions were set, the error will go away. + +[ce-4040]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4040 +[ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845 +[ce-17894]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17894 +[docker-docs]: https://docs.docker.com/engine/userguide/intro/ +[pat]: ../profile/personal_access_tokens.md +[pdt]: ../project/deploy_tokens/index.md +[reconfigure]: ../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index ca5b2f54e30..164d1dddff0 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -97,4 +97,4 @@ docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY [ce-17894]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17894 [ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845 [ce-18414]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18414 -[container registry]: ../../packages/container_registry/index.md +[container registry]: ../container_registry.md diff --git a/doc/user/project/img/mitmproxy-docker.png b/doc/user/project/img/mitmproxy-docker.png Binary files differnew file mode 100644 index 00000000000..aa3b6a0b830 --- /dev/null +++ b/doc/user/project/img/mitmproxy-docker.png diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 53c2194cd90..c63d5308536 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -60,7 +60,7 @@ When you create a project in GitLab, you'll have access to a large number of **GitLab CI/CD:** - [GitLab CI/CD](../../ci/README.md): GitLab's built-in [Continuous Integration, Delivery, and Deployment](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) tool - - [Container Registry](../packages/container_registry/index.md): Build and push Docker + - [Container Registry](container_registry.md): Build and push Docker images out-of-the-box - [Auto Deploy](../../ci/autodeploy/index.md): Configure GitLab CI/CD to automatically set up your app's deployment @@ -95,8 +95,8 @@ When you create a project in GitLab, you'll have access to a large number of - [Releases](releases/index.md): a way to track deliverables in your project as snapshot in time of the source, build output, and other metadata or artifacts associated with a released version of your code. -- [Maven packages](../packages/maven_repository/index.md): your private Maven repository in GitLab. **(PREMIUM)** -- [NPM packages](../packages/npm_registry/index.md): your private NPM package registry in GitLab. **(PREMIUM)** +- [Maven packages](packages/maven_repository.md): your private Maven repository in GitLab. **(PREMIUM)** +- [NPM packages](packages/npm_registry.md): your private NPM package registry in GitLab. **(PREMIUM)** - [Code owners](code_owners.md): specify code owners for certain files **(STARTER)** - [License Compliance](../application_security/license_compliance/index.md): approve and blacklist licenses for projects. **(ULTIMATE)** - [Dependency List](../application_security/dependency_list/index.md): view project dependencies. **(ULTIMATE)** diff --git a/doc/user/project/issues/img/link_zoom_call_in_issue.png b/doc/user/project/issues/img/link_zoom_call_in_issue.png Binary files differnew file mode 100644 index 00000000000..3153a0a9b07 --- /dev/null +++ b/doc/user/project/issues/img/link_zoom_call_in_issue.png diff --git a/doc/user/project/issues/img/zoom-quickaction-button.png b/doc/user/project/issues/img/zoom-quickaction-button.png Binary files differdeleted file mode 100644 index d6d691b2267..00000000000 --- a/doc/user/project/issues/img/zoom-quickaction-button.png +++ /dev/null diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 5313975908b..41a7ed09281 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -157,6 +157,19 @@ The plain text title and description of the issue fill the top center of the iss The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), allowing many formatting options. +##### Zoom call links + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/62966) in GitLab 12.0. + +Including a link to a [Zoom](https://zoom.us) call in the description of an issue +results in a **Join Zoom meeting** button at the top of the issue, just under the header. + +For example: + + + +To remove the button, edit the description and remove the Zoom call link. + #### 17. Mentions You can mention a user or a group present in your GitLab instance with `@username` or @@ -246,15 +259,3 @@ Once you write a comment, you can:  You can also close the issue from here, so you don't need to scroll to the top of the issue page. - -#### 26. Zoom Meetings - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31103) in GitLab 12.3. - -You can attach and remove Zoom meetings to issues using the `/zoom` and `/remove_zoom` [quick actions](../quick_actions.md) as part of -[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). - -Attaching a [Zoom](https://zoom.us) call an issue -results in a **Join Zoom meeting** button at the top of the issue, just under the header. - - diff --git a/doc/user/project/maven_packages.md b/doc/user/project/maven_packages.md index 4679eed5433..48835a2dac7 100644 --- a/doc/user/project/maven_packages.md +++ b/doc/user/project/maven_packages.md @@ -1,5 +1,5 @@ --- -redirect_to: '../packages/maven_repository/index.md' +redirect_to: 'packages/maven_repository.md' --- -This document was moved to [another location](../packages/maven_repository/index.md). +This document was moved to [another location](packages/maven_repository.md). diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md index 1c9157b0f67..39ca1bd0c77 100644 --- a/doc/user/project/operations/feature_flags.md +++ b/doc/user/project/operations/feature_flags.md @@ -120,8 +120,6 @@ A feature flag may be enabled for a list of target users. It is implemented using the Unleash [`userWithId`](https://unleash.github.io/docs/activation_strategy#userwithid) activation strategy. -The feature will always be enabled for all users in the list across all environments even if the matching environment spec **Status** is disabled. -  CAUTION: **Caution:** diff --git a/doc/user/project/packages/maven.md b/doc/user/project/packages/maven.md index 8378b8c78cd..266225fdb8d 100644 --- a/doc/user/project/packages/maven.md +++ b/doc/user/project/packages/maven.md @@ -1,5 +1,5 @@ --- -redirect_to: '../../packages/maven_repository/index.md' +redirect_to: 'maven_repository.md' --- -This document was moved to [another location](../../packages/maven_repository/index.md). +This document was moved to [another location](maven_repository.md). diff --git a/doc/user/project/packages/maven_packages.md b/doc/user/project/packages/maven_packages.md index 8378b8c78cd..266225fdb8d 100644 --- a/doc/user/project/packages/maven_packages.md +++ b/doc/user/project/packages/maven_packages.md @@ -1,5 +1,5 @@ --- -redirect_to: '../../packages/maven_repository/index.md' +redirect_to: 'maven_repository.md' --- -This document was moved to [another location](../../packages/maven_repository/index.md). +This document was moved to [another location](maven_repository.md). diff --git a/doc/user/project/packages/maven_repository.md b/doc/user/project/packages/maven_repository.md index 8378b8c78cd..491ebc0c068 100644 --- a/doc/user/project/packages/maven_repository.md +++ b/doc/user/project/packages/maven_repository.md @@ -1,5 +1,340 @@ ---- -redirect_to: '../../packages/maven_repository/index.md' ---- +# GitLab Maven Repository **(PREMIUM)** -This document was moved to [another location](../../packages/maven_repository/index.md). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5811) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. + +With the GitLab [Maven](https://maven.apache.org) Repository, every +project can have its own space to store its Maven artifacts. + + + +## Enabling the Maven Repository + +NOTE: **Note:** +This option is available only if your GitLab administrator has +[enabled support for the Maven repository](../../../administration/packages.md).**(PREMIUM ONLY)** + +After the Packages feature is enabled, the Maven Repository will be available for +all new projects by default. To enable it for existing projects, or if you want +to disable it: + +1. Navigate to your project's **Settings > General > Permissions**. +1. Find the Packages feature and enable or disable it. +1. Click on **Save changes** for the changes to take effect. + +You should then be able to see the **Packages** section on the left sidebar. +Next, you must configure your project to authorize with the GitLab Maven +repository. + +## Authenticating to the GitLab Maven Repository + +If a project is private or you want to upload Maven artifacts to GitLab, +credentials will need to be provided for authorization. Support is available for +[personal access tokens](#authenticating-with-a-personal-access-token) and +[CI job tokens](#authenticating-with-a-ci-job-token) only. +[Deploy tokens](../deploy_tokens/index.md) and regular username/password +credentials do not work. + +### Authenticating with a personal access token + +To authenticate with a [personal access token](../../profile/personal_access_tokens.md), +add a corresponding section to your +[`settings.xml`](https://maven.apache.org/settings.html) file: + +```xml +<settings> + <servers> + <server> + <id>gitlab-maven</id> + <configuration> + <httpHeaders> + <property> + <name>Private-Token</name> + <value>REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN</value> + </property> + </httpHeaders> + </configuration> + </server> + </servers> +</settings> +``` + +You should now be able to upload Maven artifacts to your project. + +### Authenticating with a CI job token + +If you're using Maven with GitLab CI/CD, a CI job token can be used instead +of a personal access token. + +To authenticate with a CI job token, add a corresponding section to your +[`settings.xml`](https://maven.apache.org/settings.html) file: + +```xml +<settings> + <servers> + <server> + <id>gitlab-maven</id> + <configuration> + <httpHeaders> + <property> + <name>Job-Token</name> + <value>${env.CI_JOB_TOKEN}</value> + </property> + </httpHeaders> + </configuration> + </server> + </servers> +</settings> +``` + +You can read more on +[how to create Maven packages using GitLab CI/CD](#creating-maven-packages-with-gitlab-cicd). + +## Configuring your project to use the GitLab Maven repository URL + +To download and upload packages from GitLab, you need a `repository` and +`distributionManagement` section in your `pom.xml` file. + +Depending on your workflow and the amount of Maven packages you have, there are +3 ways you can configure your project to use the GitLab endpoint for Maven packages: + +- **Project level**: Useful when you have few Maven packages which are not under + the same GitLab group. +- **Group level**: Useful when you have many Maven packages under the same GitLab + group. +- **Instance level**: Useful when you have many Maven packages under different + GitLab groups or on their own namespace. + +NOTE: **Note:** +In all cases, you need a project specific URL for uploading a package in +the `distributionManagement` section. + +### Project level Maven endpoint + +The example below shows how the relevant `repository` section of your `pom.xml` +would look like: + +```xml +<repositories> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </repository> +</repositories> +<distributionManagement> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </repository> + <snapshotRepository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </snapshotRepository> +</distributionManagement> +``` + +The `id` must be the same with what you +[defined in `settings.xml`](#authenticating-to-the-gitlab-maven-repository). + +Replace `PROJECT_ID` with your project ID which can be found on the home page +of your project. + +If you have a self-hosted GitLab installation, replace `gitlab.com` with your +domain name. + +NOTE: **Note:** +For retrieving artifacts, you can use either the +[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the project +(e.g., `group%2Fproject`) or the project's ID (e.g., `42`). However, only the +project's ID can be used for uploading. + +### Group level Maven endpoint + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/8798) in GitLab Premium 11.7. + +If you rely on many packages, it might be inefficient to include the `repository` section +with a unique URL for each package. Instead, you can use the group level endpoint for +all your Maven packages stored within one GitLab group. Only packages you have access to +will be available for download. + +The group level endpoint works with any package names, which means the you +have the flexibility of naming compared to [instance level endpoint](#instance-level-maven-endpoint). +However, GitLab will not guarantee the uniqueness of the package names within +the group. You can have two projects with the same package name and package +version. As a result, GitLab will serve whichever one is more recent. + +The example below shows how the relevant `repository` section of your `pom.xml` +would look like. You still need a project specific URL for uploading a package in +the `distributionManagement` section: + +```xml +<repositories> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/groups/my-group/-/packages/maven</url> + </repository> +</repositories> +<distributionManagement> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </repository> + <snapshotRepository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </snapshotRepository> +</distributionManagement> +``` + +The `id` must be the same with what you +[defined in `settings.xml`](#authenticating-to-the-gitlab-maven-repository). + +Replace `my-group` with your group name and `PROJECT_ID` with your project ID +which can be found on the home page of your project. + +If you have a self-hosted GitLab installation, replace `gitlab.com` with your +domain name. + +NOTE: **Note:** +For retrieving artifacts, you can use either the +[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the group +(e.g., `group%2Fsubgroup`) or the group's ID (e.g., `12`). + +### Instance level Maven endpoint + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/8274) in GitLab Premium 11.7. + +If you rely on many packages, it might be inefficient to include the `repository` section +with a unique URL for each package. Instead, you can use the instance level endpoint for +all maven packages stored in GitLab and the packages you have access to will be available +for download. + +Note that **only packages that have the same path as the project** are exposed via +the instance level endpoint. + +| Project | Package | Instance level endpoint available | +| ------- | ------- | --------------------------------- | +| `foo/bar` | `foo/bar/1.0-SNAPSHOT` | Yes | +| `gitlab-org/gitlab-ce` | `foo/bar/1.0-SNAPSHOT` | No | +| `gitlab-org/gitlab-ce` | `gitlab-org/gitlab-ce/1.0-SNAPSHOT` | Yes | + +The example below shows how the relevant `repository` section of your `pom.xml` +would look like. You still need a project specific URL for uploading a package in +the `distributionManagement` section: + +```xml +<repositories> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/packages/maven</url> + </repository> +</repositories> +<distributionManagement> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </repository> + <snapshotRepository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </snapshotRepository> +</distributionManagement> +``` + +The `id` must be the same with what you +[defined in `settings.xml`](#authenticating-to-the-gitlab-maven-repository). + +Replace `PROJECT_ID` with your project ID which can be found on the home page +of your project. + +If you have a self-hosted GitLab installation, replace `gitlab.com` with your +domain name. + +NOTE: **Note:** +For retrieving artifacts, you can use either the +[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the project +(e.g., `group%2Fproject`) or the project's ID (e.g., `42`). However, only the +project's ID can be used for uploading. + +## Uploading packages + +Once you have set up the [authentication](#authenticating-to-the-gitlab-maven-repository) +and [configuration](#configuring-your-project-to-use-the-gitlab-maven-repository-url), +test to upload a Maven artifact from a project of yours: + +```sh +mvn deploy +``` + +You can then navigate to your project's **Packages** page and see the uploaded +artifacts or even delete them. + +## Creating Maven packages with GitLab CI/CD + +Once you have your repository configured to use the GitLab Maven Repository, +you can configure GitLab CI/CD to build new packages automatically. The example below +shows how to create a new package each time the `master` branch is updated: + +1. Create a `ci_settings.xml` file that will serve as Maven's `settings.xml` file. + Add the server section with the same id you defined in your `pom.xml` file. + For example, in our case it's `gitlab-maven`: + + ```xml + <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"> + <servers> + <server> + <id>gitlab-maven</id> + <configuration> + <httpHeaders> + <property> + <name>Job-Token</name> + <value>${env.CI_JOB_TOKEN}</value> + </property> + </httpHeaders> + </configuration> + </server> + </servers> + </settings> + ``` + +1. Make sure your `pom.xml` file includes the following: + + ```xml + <repositories> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + </repository> + </repositories> + <distributionManagement> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + </repository> + <snapshotRepository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + </snapshotRepository> + </distributionManagement> + ``` + + TIP: **Tip:** + You can either let Maven utilize the CI environment variables or hardcode your project's ID. + +1. Add a `deploy` job to your `.gitlab-ci.yml` file: + + ```yaml + deploy: + image: maven:3.3.9-jdk-8 + script: + - 'mvn deploy -s ci_settings.xml' + only: + - master + ``` + +1. Push those files to your repository. + +The next time the `deploy` job runs, it will copy `ci_settings.xml` to the +user's home location (in this case the user is `root` since it runs in a +Docker container), and Maven will utilize the configured CI +[environment variables](../../../ci/variables/README.md#predefined-environment-variables). diff --git a/doc/user/project/packages/npm_registry.md b/doc/user/project/packages/npm_registry.md index e94599cf33a..48186688da9 100644 --- a/doc/user/project/packages/npm_registry.md +++ b/doc/user/project/packages/npm_registry.md @@ -1,5 +1,147 @@ ---- -redirect_to: '../../packages/npm_registry/index.md' ---- +# GitLab NPM Registry **(PREMIUM)** -This document was moved to [another location](../../packages/npm_registry/index.md). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. + +With the GitLab NPM Registry, every +project can have its own space to store NPM packages. + + + +NOTE: **Note:** +Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported. + +## Enabling the NPM Registry + +NOTE: **Note:** +This option is available only if your GitLab administrator has +[enabled support for the NPM registry](../../../administration/packages.md).**(PREMIUM ONLY)** + +After the NPM registry is enabled, it will be available for all new projects +by default. To enable it for existing projects, or if you want to disable it: + +1. Navigate to your project's **Settings > General > Permissions**. +1. Find the Packages feature and enable or disable it. +1. Click on **Save changes** for the changes to take effect. + +You should then be able to see the **Packages** section on the left sidebar. + +Before proceeding to authenticating with the GitLab NPM Registry, you should +get familiar with the package naming convention. + +## Package naming convention + +**Packages must be scoped in the root namespace of the project**. The package +name may be anything but it is preferred that the project name be used unless +it is not possible due to a naming collision. For example: + +| Project | Package | Supported | +| ---------------------- | ----------------------- | --------- | +| `foo/bar` | `@foo/bar` | Yes | +| `foo/bar/baz` | `@foo/baz` | Yes | +| `foo/bar/buz` | `@foo/anything` | Yes | +| `gitlab-org/gitlab-ce` | `@gitlab-org/gitlab-ce` | Yes | +| `gitlab-org/gitlab-ce` | `@foo/bar` | No | + +Now, you can configure your project to authenticate with the GitLab NPM +Registry. + +## Authenticating to the GitLab NPM Registry + +If a project is private or you want to upload an NPM package to GitLab, +credentials will need to be provided for authentication. Support is available for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow) or [personal access tokens](../../profile/personal_access_tokens.md). + +CAUTION: **2FA is only supported with personal access tokens:** +If you have 2FA enabled, you need to use a [personal access token](../../profile/personal_access_tokens.md) with OAuth headers. Standard OAuth tokens won't be able to authenticate to the GitLab NPM Registry. + +### Authenticating with an OAuth token + +To authenticate with an [OAuth token](../../../api/oauth2.md#resource-owner-password-credentials-flow) +or [personal access token](../../profile/personal_access_tokens.md), add a corresponding section to your `.npmrc` file: + +```ini +; Set URL for your scoped packages. +; For example package with name `@foo/bar` will use this URL for download +@foo:registry=https://gitlab.com/api/v4/packages/npm/ + +; Add the token for the scoped packages URL. This will allow you to download +; `@foo/` packages from private projects. +//gitlab.com/api/v4/packages/npm/:_authToken=<your_token> + +; Add token for uploading to the registry. Replace <your_project_id> +; with the project you want your package to be uploaded to. +//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_token> +``` + +Replace `<your_project_id>` with your project ID which can be found on the home page +of your project and `<your_token>` with your OAuth or personal access token. + +If you have a self-hosted GitLab installation, replace `gitlab.com` with your +domain name. + +You should now be able to download and upload NPM packages to your project. + +NOTE: **Note:** +If you encounter an error message with [Yarn](https://yarnpkg.com/en/), see the +[troubleshooting section](#troubleshooting). + +## Uploading packages + +Before you will be able to upload a package, you need to specify the registry +for NPM. To do this, add the following section to the bottom of `package.json`: + +```json + "publishConfig": { + "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/" + } +``` + +Replace `<your_project_id>` with your project ID, which can be found on the home +page of your project, and replace `@foo` with your own scope. + +If you have a self-hosted GitLab installation, replace `gitlab.com` with your +domain name. + +Once you have enabled it and set up [authentication](#authenticating-to-the-gitlab-npm-registry), +you can upload an NPM package to your project: + +```sh +npm publish +``` + +You can then navigate to your project's **Packages** page and see the uploaded +packages or even delete them. + +If you attempt to publish a package with a name that already exists within +a given scope, you will receive a `403 Forbidden!` error. + +## Uploading a package with the same version twice + +If you upload a package with a same name and version twice, GitLab will show +both packages in the UI, but the GitLab NPM Registry will expose the most recent +one as it supports only one package per version for `npm install`. + +## Troubleshooting + +### Error running yarn with NPM registry + +If you are using [yarn](https://yarnpkg.com/en/) with the NPM registry, you may get +an error message like: + +```sh +yarn install v1.15.2 +warning package.json: No license field +info No lockfile found. +warning XXX: No license field +[1/4] 🔍 Resolving packages... +[2/4] 🚚 Fetching packages... +error An unexpected error occurred: "https://gitlab.com/api/v4/projects/XXX/packages/npm/XXX/XXX/-/XXX/XXX-X.X.X.tgz: Request failed \"404 Not Found\"". +info If you think this is a bug, please open a bug report with the information provided in "/Users/XXX/gitlab-migration/module-util/yarn-error.log". +info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command +``` + +In this case, try adding this to your `.npmrc` file (and replace `<your_oauth_token>` +with your with your OAuth or personal access token): + +```text +//gitlab.com/api/v4/projects/:_authToken=<your_oauth_token> +``` diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index 3c15d41e1ba..ef90899c512 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -9,11 +9,11 @@ type: reference, howto > - In GitLab 8.17, builds were renamed to jobs. > - The artifacts browser will be available only for new artifacts that are sent to GitLab using GitLab Runner version 1.0 and up. It will not be possible to browse old artifacts already uploaded to GitLab. -Job artifacts are a list of files and directories created by a job +Artifacts are a list of files and directories which created by a job once it finishes. This feature is [enabled by default](../../../administration/job_artifacts.md) in all GitLab installations. -Job artifacts created by GitLab Runner are uploaded to GitLab and are downloadable as a single archive using the GitLab UI or the [GitLab API](../../../api/jobs.md#get-job-artifacts). +Job artifacts that are created by GitLab Runner are uploaded to GitLab and are downloadable as a single archive using the GitLab UI. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, watch the video [GitLab CI Pipeline, Artifacts, and Environments](https://www.youtube.com/watch?v=PCKDICEe10s). @@ -78,7 +78,7 @@ one HTML file that you can view directly online when ## Downloading artifacts If you need to download the whole archive, there are buttons in various places -in the GitLab UI to do this: +inside GitLab that make that possible. 1. While on the pipelines page, you can see the download icon for each job's artifacts archive in the right corner: diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 66a861faf93..e0fb5c57784 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -22,7 +22,7 @@ The project description also partially supports [standard markdown](../../markdo ### Sharing and permissions -Set up your project's access, [visibility](../../../public_access/public_access.md), and enable [Container Registry](../../packages/container_registry/index.md) for your projects: +Set up your project's access, [visibility](../../../public_access/public_access.md), and enable [Container Registry](../container_registry.md) for your projects:  diff --git a/doc/user/project/wiki/img/wiki_create_new_page_modal.png b/doc/user/project/wiki/img/wiki_create_new_page_modal.png Binary files differnew file mode 100644 index 00000000000..b800508901b --- /dev/null +++ b/doc/user/project/wiki/img/wiki_create_new_page_modal.png diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index c0159230fec..d1bab47de25 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -30,12 +30,10 @@ Requires Developer [permissions](../../permissions.md). Create a new page by clicking the **New page** button that can be found in all wiki pages. -You will be asked to fill in a title for your new wiki page. - -You can specify a full path for the wiki page by using '/' in the -title to indicate subdirectories. Any missing directories will be created -automatically. For example, a title of `docs/my-page` will create a wiki -page with a path `/wikis/docs/my-page`. +You will be asked to fill in a title for your new wiki page. Wiki titles +also determine the path to the wiki page. You can specify a full path +(using "`/`" for subdirectories) for the new title and any missing +directories will be created automatically. Once you enter the page name, it's time to fill in its content. GitLab wikis support Markdown, RDoc and AsciiDoc. For Markdown based pages, all the |
