Skip to content

G
gitlab-ce
Commit b5987304 authored by Evan Read's avatar Evan Read
Browse files
Options

Merge branch 'docs/npm-packages-refactor' into 'master' 

Refactor the Packages documentation

See merge request gitlab-org/gitlab-ee!9095
parents 4d165bb8 c4f0a1c5
Hide whitespace changes
Inline Side-by-side
Showing with 86 additions and 89 deletions
doc/administration/index.md
View file @ b5987304
......@@ -126,8 +126,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
- [Default labels](../user/admin_area/labels.html): Create labels that will be automatically added to every new project.
- [Restrict the use of public or internal projects](../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects): Restrict the use of visibility levels for users when they create a project or a snippet.
- [Custom project templates](../user/admin_area/custom_project_templates.md): Configure a set of projects to be used as custom templates when creating a new project. **[PREMIUM ONLY]**
- [Maven Repository](maven_repository.md): Enable Maven Repository within GitLab. **[PREMIUM ONLY]**
- [NPM Registry](npm_registry.md): Enable NPM Registry within GitLab. **[PREMIUM ONLY]**
- [Packages](packages.md): Enable GitLab to act as a Maven repository or NPM registry. **[PREMIUM ONLY]**
### Repository settings
......
doc/administration/maven_packages.md
View file @ b5987304
This document was moved to [another location](maven_repository.md).
This document was moved to [another location](packages.md).
doc/administration/maven_repository.md
View file @ b5987304
# GitLab Maven Repository administration **[PREMIUM ONLY]**
>
[Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5811)
in GitLab 11.3. To learn how to use
When the GitLab Maven Repository is enabled, every project in GitLab will have
its own space to store [Maven](https://maven.apache.org/) packages.
To learn how to use it, see the [user documentation](../user/project/packages/maven_repository.md).
## Enabling the Maven Repository
NOTE: **Note:**
Once enabled, newly created projects will have the Packages feature enabled by
default. Existing projects will need to
[explicitly enabled it](../user/project/packages/maven_repository.md#enabling-the-packages-repository).
To enable the Maven repository you need to enable [Packages feature](packages.md)
This document was moved to [another location](packages.md).
doc/administration/npm_registry.md
View file @ b5987304
# GitLab NPM Registry administration **[PREMIUM ONLY]**
>
[Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5934)
in GitLab 11.7. To learn how to use
When the GitLab NPM Registry is enabled, every project in GitLab will have
its own space to store [NPM](https://www.npmjs.com/) packages.
To learn how to use it, see the [user documentation](../user/project/packages/npm_registry.md).
## Enabling the NPM Registry
NOTE: **Note:**
Once enabled, newly created projects will have the Packages feature enabled by
default. Existing projects will need to
[explicitly enabled it](../user/project/packages/npm_registry.md#enabling-the-packages-repository).
To enable the NPM Registry you need to enable [Packages feature](packages.md)
This document was moved to [another location](packages.md).
doc/administration/packages.md
View file @ b5987304
# GitLab Packages administration **[PREMIUM ONLY]**
Package feature provides a support for next products:
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.
* [Maven Repository](maven_repository.md)
* [NPM Registry](npm_registry.md)
The Packages feature allows GitLab to act as a repository for the following:
| Software repository | Description | Available in GitLab version |
| ------------------- | ----------- | --------------------------- |
| [Maven Repository](../user/project/packages/maven_repository.md) | 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](../user/project/packages/npm_registry.md) | The GitLab NPM Registry enables every project in GitLab to have its own space to store [NPM](https://www.npmjs.com/) packages. | 11.7+ |
## Enabling the Packages feature
NOTE: **Note:**
After the Packages feature is enabled, the repositories are available for
for all new projects by default. To enable it for existing projects, users will
have to explicitly do so in the project's settings.
To enable the Packages feature:
**Omnibus GitLab installations**
......
doc/user/project/packages/maven_repository.md
View file @ b5987304
# GitLab Maven Repository **[PREMIUM]**
> Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3.
> [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.
![GitLab Maven Repository](img/maven_package_view.png)
## Enabling Maven Repository
## Enabling the Maven Repository
NOTE: **Note:**
This option is available only if your GitLab administrator has
[enabled Maven Repository](../../../administration/maven_repository.md).
[enabled support for the Maven repository](../../../administration/packages.md).
In order to use the GitLab Maven Repository, you must enable the
Repository. To enable (or disable) it:
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 it.
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.
......
doc/user/project/packages/npm_registry.md
View file @ b5987304
# GitLab NPM Registry **[PREMIUM]**
> Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7.
> [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.
......@@ -8,77 +9,97 @@ project can have its own space to store NPM packages.
![GitLab NPM Registry](img/npm_package_view.png)
NOTE: **Note:**
Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported.
Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported.
## Enabling NPM Registry
## Enabling the NPM Registry
NOTE: **Note:**
This option is available only if your GitLab administrator has
[enabled Packages feature](../../../administration/npm_registry.md).
[enabled support for the NPM registry](../../../administration/packages.md).
In order to use the GitLab NPM Registry, you must enable the Packages feature.
To enable (or disable) it:
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 it.
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 NPM
registry.
Before proceeding to authenticating with the GitLab NPM Registry, you should
get familiar with the package naming convention.
## Package naming convention
Note that **only packages that have the same path as the project** are supported.
**Only packages that have the same path as the project** are supported. For
example:
| Project | Package | Supported |
| ---------------------- | ----------------------- | --------- |
| `foo/bar` | `@foo/bar` | Yes |
| `gitlab-org/gitlab-ce` | `@gitlab-org/gitlab-ce` | Yes |
| `gitlab-org/gitlab-ce` | `@foo/bar` | No |
| Project | Package | Supported |
| ------- | ------- | --------------------------------- |
| `foo/bar` | `@foo/bar` | Yes |
| `gitlab-org/gitlab-ce` | `@foo/bar` | No |
| `gitlab-org/gitlab-ce` | `@gitlab-org/gitlab-ce` | Yes |
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 NPM package to GitLab,
credentials will need to be provided for authentication. Support is available for
[oauth tokens](#authenticating-with-an-oauth-token) only.
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
only for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow).
### Authenticating with an oauth token
CAUTION: **2FA not supported:**
Authentication for personal access tokens is not yet supported
([#9140](https://gitlab.com/gitlab-org/gitlab-ee/issues/9140)). If you have 2FA
enabled, you won't be able to authenticate to the GitLab NPM Registry.
To authenticate with a [oauth token](../../../api/oauth2.md),
### Authenticating with an OAuth token
To authenticate with an [OAuth token](../../../api/oauth2.md#resource-owner-password-credentials-flow),
add a corresponding section to your `.npmrc` file:
```
; Set URL for your scoped packages.
; For example package with name `@foo/bar` will use this URL for download
```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 OAuth token for scoped packages URL. This will allow you to download
; `@foo/` packages from private projects.
//localhost:3001/api/v4/packages/npm/:_authToken=1da4f6691c92a543f7416b8fe013357fda23b0730466841311b89809a51349ce
; Add the OAuth 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_oauth_token>
; Add OAuth token for uploading to the registry. Replace `YOUR_PROJECT_ID`
; with a project you want your package uploaded to.
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=YOUR_OAUTH_TOKEN
; Add OAuth 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_oauth_token>
```
Replace `<your_project_id>` with your project ID which can be found on the home page
of your project and `<your_oauth_token>` with your OAuth 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.
## Uploading packages
Before you will be able to upload a package, you need to specify registry for NPM.
To do this, you need to add next section to the bottom of `package.json`:
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/"
"@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/"
}
```
Replace `YOUR_PROJECT_ID` with a project you want your package uploaded to.
And replace `@foo` with your own scope.
Once you did it and have set up the [authorization](#authorizing-with-the-gitlab-npm-registry),
test to upload an NPM package from a project of yours:
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
......@@ -89,6 +110,6 @@ packages or even delete them.
## 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 UI. But API will expose only one package per version for `npm install`
and it will be the most recent one.
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`.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7