diff options
Diffstat (limited to 'doc/user/project')
| -rw-r--r-- | doc/user/project/container_registry.md | 320 | ||||
| -rw-r--r-- | doc/user/project/deploy_tokens/index.md | 2 | ||||
| -rw-r--r-- | doc/user/project/img/mitmproxy-docker.png | bin | 0 -> 142591 bytes | |||
| -rw-r--r-- | doc/user/project/index.md | 6 | ||||
| -rw-r--r-- | doc/user/project/issues/img/link_zoom_call_in_issue.png | bin | 0 -> 69554 bytes | |||
| -rw-r--r-- | doc/user/project/issues/img/zoom-quickaction-button.png | bin | 117097 -> 0 bytes | |||
| -rw-r--r-- | doc/user/project/issues/issue_data_and_actions.md | 25 | ||||
| -rw-r--r-- | doc/user/project/maven_packages.md | 4 | ||||
| -rw-r--r-- | doc/user/project/operations/feature_flags.md | 2 | ||||
| -rw-r--r-- | doc/user/project/packages/maven.md | 4 | ||||
| -rw-r--r-- | doc/user/project/packages/maven_packages.md | 4 | ||||
| -rw-r--r-- | doc/user/project/packages/maven_repository.md | 343 | ||||
| -rw-r--r-- | doc/user/project/packages/npm_registry.md | 150 | ||||
| -rw-r--r-- | doc/user/project/pipelines/job_artifacts.md | 6 | ||||
| -rw-r--r-- | doc/user/project/settings/index.md | 2 | ||||
| -rw-r--r-- | doc/user/project/wiki/img/wiki_create_new_page_modal.png | bin | 0 -> 5831 bytes | |||
| -rw-r--r-- | doc/user/project/wiki/index.md | 10 |
17 files changed, 832 insertions, 46 deletions
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 |
