diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2019-09-17 12:06:48 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2019-09-17 12:06:48 +0000 |
| commit | bd860c22f6a4b9473cbddd34a53eead8235a7ea1 (patch) | |
| tree | 3f955a56c2ac90497863da26902a42dba49f3466 /doc/user | |
| parent | e567b4c2df7dc4085d213db029eff6b6fcde0152 (diff) | |
| download | gitlab-ce-bd860c22f6a4b9473cbddd34a53eead8235a7ea1.tar.gz | |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/user')
28 files changed, 787 insertions, 908 deletions
diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index cb802612b56..7c24edb8558 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -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](../../project/container_registry.md). + your Docker image to your project's [Container Registry](../../packages/container_registry/index.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](../../project/container_registry.md) (see [requirements](#requirements)) + [Container Registry](../../packages/container_registry/index.md) (see [requirements](#requirements)) and scan it for possible vulnerabilities. The results will be saved as a diff --git a/doc/user/group/dependency_proxy/index.md b/doc/user/group/dependency_proxy/index.md index 771468fbba8..f735ec0214f 100644 --- a/doc/user/group/dependency_proxy/index.md +++ b/doc/user/group/dependency_proxy/index.md @@ -1,74 +1,5 @@ -# Dependency Proxy **(PREMIUM)** +--- +redirect_to: '../../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. +This document was moved to [another location](../../packages/dependency_proxy/index.md). diff --git a/doc/user/group/index.md b/doc/user/group/index.md index c09acd36e31..a0bdb737466 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](../project/container_registry.md) tags, +project with [Container Registry](../packages/container_registry/index.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](dependency_proxy/index.md) for upstream Docker images. +Use GitLab as a [dependency proxy](../packages/dependency_proxy/index.md) for upstream Docker images. <!-- ## Troubleshooting diff --git a/doc/user/index.md b/doc/user/index.md index 27e75189fc3..e1833cab6b8 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](project/container_registry.md). +- Integrating with Docker by using [GitLab Container Registry](packages/container_registry/index.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](project/container_registry.md): Build and deploy Docker +- [GitLab Container Registry](packages/container_registry/index.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 new file mode 100644 index 00000000000..710e7bd405b --- /dev/null +++ b/doc/user/packages/container_registry/index.md @@ -0,0 +1,158 @@ +# 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 differnew file mode 100644 index 00000000000..035aff0b6c4 --- /dev/null +++ b/doc/user/packages/dependency_proxy/img/group_dependency_proxy.png diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md new file mode 100644 index 00000000000..8c337f74dcf --- /dev/null +++ b/doc/user/packages/dependency_proxy/index.md @@ -0,0 +1,74 @@ +# 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 new file mode 100644 index 00000000000..506eb5703a6 --- /dev/null +++ b/doc/user/packages/index.md @@ -0,0 +1,19 @@ +# 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 differnew file mode 100644 index 00000000000..2eb4b6f76b4 --- /dev/null +++ b/doc/user/packages/maven_repository/img/maven_package_view.png diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md new file mode 100644 index 00000000000..2c400653fcc --- /dev/null +++ b/doc/user/packages/maven_repository/index.md @@ -0,0 +1,340 @@ +# 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 differnew file mode 100644 index 00000000000..e0634718c02 --- /dev/null +++ b/doc/user/packages/npm_registry/img/npm_package_view.png diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md new file mode 100644 index 00000000000..30de301b96a --- /dev/null +++ b/doc/user/packages/npm_registry/index.md @@ -0,0 +1,147 @@ +# 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 46a3090e268..8232ae44c68 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](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)** | | | ✓ | ✓ | ✓ | +| 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)** | | | ✓ | ✓ | ✓ | | 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 40b7294c3bb..d9144f9b5fd 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](../project/container_registry.md) tags, +project with [Container Registry](../packages/container_registry/index.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 d556daa3460..ffe6104698f 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]: ../project/container_registry.md +[container registry]: ../packages/container_registry/index.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 c9eb81b990c..91c9d3171dc 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -1,317 +1,5 @@ -# GitLab Container Registry +--- +redirect_to: '../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 +This document was moved to [another location](../packages/container_registry/index.md). diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 164d1dddff0..ca5b2f54e30 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]: ../container_registry.md +[container registry]: ../../packages/container_registry/index.md diff --git a/doc/user/project/img/mitmproxy-docker.png b/doc/user/project/img/mitmproxy-docker.png Binary files differdeleted file mode 100644 index aa3b6a0b830..00000000000 --- a/doc/user/project/img/mitmproxy-docker.png +++ /dev/null diff --git a/doc/user/project/index.md b/doc/user/project/index.md index c63d5308536..53c2194cd90 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](container_registry.md): Build and push Docker + - [Container Registry](../packages/container_registry/index.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.md): your private Maven repository in GitLab. **(PREMIUM)** -- [NPM packages](packages/npm_registry.md): your private NPM package registry in GitLab. **(PREMIUM)** +- [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)** - [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 differdeleted file mode 100644 index 3153a0a9b07..00000000000 --- a/doc/user/project/issues/img/link_zoom_call_in_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/zoom-quickaction-button.png b/doc/user/project/issues/img/zoom-quickaction-button.png Binary files differnew file mode 100644 index 00000000000..d6d691b2267 --- /dev/null +++ b/doc/user/project/issues/img/zoom-quickaction-button.png diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 41a7ed09281..5313975908b 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -157,19 +157,6 @@ 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 @@ -259,3 +246,15 @@ 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 48835a2dac7..4679eed5433 100644 --- a/doc/user/project/maven_packages.md +++ b/doc/user/project/maven_packages.md @@ -1,5 +1,5 @@ --- -redirect_to: 'packages/maven_repository.md' +redirect_to: '../packages/maven_repository/index.md' --- -This document was moved to [another location](packages/maven_repository.md). +This document was moved to [another location](../packages/maven_repository/index.md). diff --git a/doc/user/project/packages/maven.md b/doc/user/project/packages/maven.md index 266225fdb8d..8378b8c78cd 100644 --- a/doc/user/project/packages/maven.md +++ b/doc/user/project/packages/maven.md @@ -1,5 +1,5 @@ --- -redirect_to: 'maven_repository.md' +redirect_to: '../../packages/maven_repository/index.md' --- -This document was moved to [another location](maven_repository.md). +This document was moved to [another location](../../packages/maven_repository/index.md). diff --git a/doc/user/project/packages/maven_packages.md b/doc/user/project/packages/maven_packages.md index 266225fdb8d..8378b8c78cd 100644 --- a/doc/user/project/packages/maven_packages.md +++ b/doc/user/project/packages/maven_packages.md @@ -1,5 +1,5 @@ --- -redirect_to: 'maven_repository.md' +redirect_to: '../../packages/maven_repository/index.md' --- -This document was moved to [another location](maven_repository.md). +This document was moved to [another location](../../packages/maven_repository/index.md). diff --git a/doc/user/project/packages/maven_repository.md b/doc/user/project/packages/maven_repository.md index 491ebc0c068..8378b8c78cd 100644 --- a/doc/user/project/packages/maven_repository.md +++ b/doc/user/project/packages/maven_repository.md @@ -1,340 +1,5 @@ -# GitLab Maven Repository **(PREMIUM)** +--- +redirect_to: '../../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). +This document was moved to [another location](../../packages/maven_repository/index.md). diff --git a/doc/user/project/packages/npm_registry.md b/doc/user/project/packages/npm_registry.md index 48186688da9..e94599cf33a 100644 --- a/doc/user/project/packages/npm_registry.md +++ b/doc/user/project/packages/npm_registry.md @@ -1,147 +1,5 @@ -# GitLab NPM Registry **(PREMIUM)** +--- +redirect_to: '../../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> -``` +This document was moved to [another location](../../packages/npm_registry/index.md). diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index e0fb5c57784..66a861faf93 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](../container_registry.md) for your projects: +Set up your project's access, [visibility](../../../public_access/public_access.md), and enable [Container Registry](../../packages/container_registry/index.md) for your projects:  |
