Docs: Merge 4 EE doc/user/project dirs to CE
This commit is contained in:
parent
96e5c4e214
commit
4d4bb01d53
|
@ -0,0 +1,177 @@
|
|||
# Feature Flags **[PREMIUM]**
|
||||
|
||||
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845) in GitLab 11.4.
|
||||
|
||||
CAUTION: **Warning:**
|
||||
This an _alpha_ feature and is subject to change at any time without
|
||||
prior notice.
|
||||
|
||||
Feature flags allow you to ship a project in different flavors by
|
||||
dynamically toggling certain functionality.
|
||||
|
||||
## Overview
|
||||
|
||||
Feature Flags offer a feature toggle system for your application. They enable teams
|
||||
to achieve Continuous Delivery by deploying new features to production at smaller
|
||||
batches for controlled testing, separating feature delivery from customer launch.
|
||||
This helps reducing risk and allows you to easily manage which features to enable.
|
||||
|
||||
GitLab offers a Feature Flags interface that allows you to create, toggle and
|
||||
remove feature flags.
|
||||
|
||||
## How it works
|
||||
|
||||
Underneath, GitLab uses [unleash](https://github.com/Unleash/unleash), a feature
|
||||
toggle service. GitLab provides an API where your application can talk to and get the
|
||||
list of feature flags you set in GitLab.
|
||||
|
||||
The application must be configured to talk to GitLab, so that's up to the
|
||||
developers to use a compatible [client library](#client-libraries) and
|
||||
integrate it in their app.
|
||||
|
||||
By setting a flag active or inactive via GitLab, your application will automatically
|
||||
know which features to enable or disable respectively.
|
||||
|
||||
## Adding a new feature flag
|
||||
|
||||
To add a new feature flag:
|
||||
|
||||
1. Navigate to your project's **Operations > Feature Flags**.
|
||||
1. Click on the **New Feature Flag** button.
|
||||
1. Give it a name.
|
||||
|
||||
NOTE: **Note:**
|
||||
A name can contain only lowercase letters, digits, underscores (`_`)
|
||||
and dashes (`-`), must start with a letter, and cannot end with a dash (`-`)
|
||||
or an underscore (`_`).
|
||||
|
||||
1. Give it a description (optional, 255 characters max).
|
||||
1. Define environment [specs](#define-environment-specs). If you want the flag on by default, enable the catch-all [wildcard spec (`*`)](#define-environment-specs)
|
||||
1. Click **Create feature flag**.
|
||||
|
||||
Once a feature flag is created, the list of existing feature flags will be presented
|
||||
with ability to edit or remove them.
|
||||
|
||||
To make a feature flag active or inactive, click the pencil icon to edit it,
|
||||
and toggle the status for each [spec](#define-environment-specs).
|
||||
|
||||
![Feature flags list](img/feature_flags_list.png)
|
||||
|
||||
## Define environment specs
|
||||
|
||||
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8621) in GitLab 11.8.
|
||||
|
||||
In general, an application is deployed to multiple environments, such as
|
||||
production, staging and [review apps](../../../ci/review_apps/index.md).
|
||||
For example, you may not want to enable a feature flag on production until your QA team has
|
||||
first confirmed that the feature is working correctly on testing environments.
|
||||
|
||||
To handle these situations, you can enable a feature flag on a particular environment
|
||||
with [Environment specs](../../../ci/environments.md#scoping-environments-with-specs-premium).
|
||||
You can define multiple specs per flag so that you can control your feature flag more granularly.
|
||||
|
||||
To define specs for each environment:
|
||||
|
||||
1. Navigate to your project's **Operations > Feature Flags**.
|
||||
1. Click on the **New Feature Flag** button or edit an existing flag.
|
||||
1. Set the status of the default [spec](../../../ci/environments.md#scoping-environments-with-specs-premium) (`*`). This status will be used for _all_ environments.
|
||||
1. If you want to enable/disable the feature on a specific environment, create a new [spec](../../../ci/environments.md#scoping-environments-with-specs-premium) and type the environment name.
|
||||
1. Set the status of the additional spec. This status takes precedence over the default spec's status since we always use the most specific match available.
|
||||
1. Click **Create feature flag** or **Update feature flag**.
|
||||
|
||||
![Feature flag specs list](img/specs_list.png)
|
||||
|
||||
NOTE: **NOTE**
|
||||
We'd highly recommend you to use the [Environment](../../../ci/environments.md)
|
||||
feature in order to quickly assess which flag is enabled per environment.
|
||||
|
||||
## Integrating with your application
|
||||
|
||||
In order to use Feature Flags, you need to first
|
||||
[get the access credentials](#configuring-feature-flags) from GitLab and then
|
||||
prepare your application and hook it with a [client library](#client-libraries).
|
||||
|
||||
### Configuring Feature Flags
|
||||
|
||||
To get the access credentials that your application will need to talk to GitLab:
|
||||
|
||||
1. Navigate to your project's **Operations > Feature Flags**.
|
||||
1. Click on the **Configure** button to see the values:
|
||||
- **API URL**: URL where the client (application) connects to get a list of feature flags.
|
||||
- **Instance ID**: Unique token that authorizes the retrieval of the feature flags.
|
||||
- **Application name**: The name of the running environment. For instance,
|
||||
if the application runs for production server, application name would be
|
||||
`production` or similar. This value is used for
|
||||
[the environment spec evaluation](#define-environment-specs).
|
||||
|
||||
NOTE: **Note:**
|
||||
The meaning of these fields might change over time. For example, we are not sure
|
||||
if **Instance ID** will be single token or multiple tokens, assigned to the
|
||||
**Environment**. Also, **Application name** could describe the version of
|
||||
application instead of the running environment.
|
||||
|
||||
### Client libraries
|
||||
|
||||
GitLab currently implements a single backend that is compatible with
|
||||
[Unleash](https://github.com/Unleash/unleash#client-implementations) clients.
|
||||
|
||||
Unleash clients allow the developers to define in the app's code the default
|
||||
values for flags. Each feature flag evaluation can express the desired
|
||||
outcome in case the flag isn't present on the provided configuration file.
|
||||
|
||||
Unleash currently offers a number of official SDKs for various frameworks and
|
||||
a number of community contributed libraries.
|
||||
|
||||
Official clients:
|
||||
|
||||
- [unleash/unleash-client-java](https://github.com/unleash/unleash-client-java)
|
||||
- [unleash/unleash-client-node](https://github.com/unleash/unleash-client-node)
|
||||
- [unleash/unleash-client-go](https://github.com/unleash/unleash-client-go)
|
||||
- [unleash/unleash-client-ruby](https://github.com/unleash/unleash-client-ruby)
|
||||
|
||||
Community contributed clients:
|
||||
|
||||
- [stiano/unleash-client-dotnet](https://github.com/stiano/unleash-client-dotnet) (.Net Core)
|
||||
- [onybo/unleash-client-core](https://github.com/onybo/unleash-client-core) (.Net Core)
|
||||
- [aes/unleash-client-python](https://github.com/aes/unleash-client-python) (Python 3)
|
||||
|
||||
### Golang application example
|
||||
|
||||
Here's an example of how to integrate the feature flags in a Golang application:
|
||||
|
||||
```golang
|
||||
package main
|
||||
|
||||
import (
|
||||
"io"
|
||||
"log"
|
||||
"net/http"
|
||||
|
||||
"github.com/Unleash/unleash-client-go"
|
||||
)
|
||||
|
||||
type metricsInterface struct {
|
||||
}
|
||||
|
||||
func init() {
|
||||
unleash.Initialize(
|
||||
unleash.WithUrl("https://gitlab.com/api/v4/feature_flags/unleash/42"),
|
||||
unleash.WithInstanceId("29QmjsW6KngPR5JNPMWx"),
|
||||
unleash.WithAppName("production"),
|
||||
unleash.WithListener(&metricsInterface{}),
|
||||
)
|
||||
}
|
||||
|
||||
func helloServer(w http.ResponseWriter, req *http.Request) {
|
||||
if unleash.IsEnabled("my_feature_name") {
|
||||
io.WriteString(w, "Feature enabled\n")
|
||||
} else {
|
||||
io.WriteString(w, "hello, world!\n")
|
||||
}
|
||||
}
|
||||
|
||||
func main() {
|
||||
http.HandleFunc("/", helloServer)
|
||||
log.Fatal(http.ListenAndServe(":8080", nil))
|
||||
}
|
||||
```
|
Binary file not shown.
After Width: | Height: | Size: 15 KiB |
Binary file not shown.
After Width: | Height: | Size: 43 KiB |
|
@ -7,5 +7,5 @@ your applications:
|
|||
- Deploy to different [environments](../../../ci/environments.md).
|
||||
- Connect your project to a [Kubernetes cluster](../clusters/index.md).
|
||||
- Discover and view errors generated by your applications with [Error Tracking](error_tracking.md).
|
||||
- Create, toggle, and remove [Feature Flags](https://docs.gitlab.com/ee/user/project/operations/feature_flags.html). **[PREMIUM]**
|
||||
- [Trace](https://docs.gitlab.com/ee/user/project/operations/tracing.html) the performance and health of a deployed application. **[ULTIMATE]**
|
||||
- Create, toggle, and remove [Feature Flags](feature_flags.md). **[PREMIUM]**
|
||||
- [Trace](tracing.md) the performance and health of a deployed application. **[ULTIMATE]**
|
||||
|
|
|
@ -0,0 +1,34 @@
|
|||
# Tracing **[ULTIMATE]**
|
||||
|
||||
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/7903) in GitLab Ultimate 11.5.
|
||||
|
||||
Tracing provides insight into the performance and health of a deployed application,
|
||||
tracking each function or microservice which handles a given request.
|
||||
|
||||
This makes it easy to
|
||||
understand the end-to-end flow of a request, regardless of whether you are using a monolithic or distributed system.
|
||||
|
||||
## Jaeger tracing
|
||||
|
||||
[Jaeger](https://www.jaegertracing.io/) is an open source, end-to-end distributed
|
||||
tracing system used for monitoring and troubleshooting microservices-based distributed
|
||||
systems.
|
||||
|
||||
### Deploying Jaeger
|
||||
|
||||
To learn more about deploying Jaeger, read the official
|
||||
[Getting Started documentation](https://www.jaegertracing.io/docs/latest/getting-started/).
|
||||
There is an easy to use [all-in-one Docker image](https://www.jaegertracing.io/docs/latest/getting-started/#AllinoneDockerimage),
|
||||
as well as deployment options for [Kubernetes](https://github.com/jaegertracing/jaeger-kubernetes)
|
||||
and [OpenShift](https://github.com/jaegertracing/jaeger-openshift).
|
||||
|
||||
### Enabling Jaeger
|
||||
|
||||
GitLab provides an easy way to open the Jaeger UI from within your project:
|
||||
|
||||
1. [Set up Jaeger](#deploying-jaeger) and configure your application using one of the
|
||||
[client libraries](https://www.jaegertracing.io/docs/latest/client-libraries/).
|
||||
1. Navigate to your project's **Settings > Operations** and provide the Jaeger URL.
|
||||
1. Click **Save changes** for the changes to take effect.
|
||||
1. You can now visit **Operations > Tracing** in your project's sidebar and
|
||||
GitLab will redirect you to the configured Jaeger URL.
|
Binary file not shown.
After Width: | Height: | Size: 16 KiB |
Binary file not shown.
After Width: | Height: | Size: 24 KiB |
|
@ -0,0 +1,5 @@
|
|||
---
|
||||
redirect_to: 'maven_repository.md'
|
||||
---
|
||||
|
||||
This document was moved to [another location](maven_repository.md).
|
|
@ -0,0 +1,5 @@
|
|||
---
|
||||
redirect_to: 'maven_repository.md'
|
||||
---
|
||||
|
||||
This document was moved to [another location](maven_repository.md).
|
|
@ -0,0 +1,341 @@
|
|||
# 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.
|
||||
|
||||
![GitLab Maven Repository](img/maven_package_view.png)
|
||||
|
||||
## Enabling the Maven Repository
|
||||
|
||||
NOTE: **Note:**
|
||||
This option is available only if your GitLab administrator has
|
||||
[enabled support for the Maven repository](https://docs.gitlab.com/ee/administration/packages.html).**[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).
|
|
@ -0,0 +1,120 @@
|
|||
# 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.
|
||||
|
||||
![GitLab NPM Registry](img/npm_package_view.png)
|
||||
|
||||
NOTE: **Note:**
|
||||
Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported.
|
||||
|
||||
|
||||
NOTE: **Note:**
|
||||
As `@group/subgroup/project` is not a valid NPM package name, publishing a package
|
||||
within a subgroup is not supported yet.
|
||||
|
||||
## Enabling the NPM Registry
|
||||
|
||||
NOTE: **Note:**
|
||||
This option is available only if your GitLab administrator has
|
||||
[enabled support for the NPM registry](https://docs.gitlab.com/ee/administration/packages.html).**[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
|
||||
|
||||
**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 |
|
||||
|
||||
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
|
||||
only for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow).
|
||||
|
||||
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.
|
||||
|
||||
### 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:
|
||||
|
||||
```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 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 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 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.
|
||||
|
||||
## 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`.
|
|
@ -42,9 +42,9 @@ Set up your project's merge request settings:
|
|||
|
||||
![project's merge request settings](img/merge_requests_settings.png)
|
||||
|
||||
### Service Desk
|
||||
### Service Desk **[PREMIUM]**
|
||||
|
||||
Enable [Service Desk](https://docs.gitlab.com/ee/user/project/service_desk.html) for your project to offer customer support. Service Desk is available in [GitLab Premium](https://about.gitlab.com/pricing/).
|
||||
Enable [Service Desk](https://docs.gitlab.com/ee/user/project/service_desk.html) for your project to offer customer support.
|
||||
|
||||
### Export project
|
||||
|
||||
|
@ -128,3 +128,7 @@ namespace if needed.
|
|||
### Error Tracking
|
||||
|
||||
Configure Error Tracking to discover and view [Sentry errors within GitLab](../operations/error_tracking.md).
|
||||
|
||||
### Jaeger tracing **[ULTIMATE]**
|
||||
|
||||
Add the URL of a Jaeger server to allow your users to [easily access the Jaeger UI from within GitLab](../operations/tracing.md).
|
||||
|
|
|
@ -128,5 +128,123 @@ IDE. An example `package.json` is below.
|
|||
}
|
||||
```
|
||||
|
||||
## Interactive Web Terminals for the Web IDE **[ULTIMATE ONLY]**
|
||||
|
||||
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6.
|
||||
|
||||
CAUTION: **Warning:**
|
||||
Interactive Web Terminals for the Web IDE is currently in **Beta**.
|
||||
|
||||
[Interactive web terminals](../../../ci/interactive_web_terminal/index.md)
|
||||
give the user access to a terminal to interact with the Runner directly from
|
||||
GitLab, including through the Web IDE.
|
||||
|
||||
Only project [**maintainers**](../../permissions.md#project-members-permissions)
|
||||
can run Interactive Web Terminals through the Web IDE.
|
||||
|
||||
CAUTION: **Warning:**
|
||||
GitLab.com [does not support Interactive Web Terminals yet](https://gitlab.com/gitlab-org/gitlab-ce/issues/52611).
|
||||
Shared Runners in private instances are not supported either.
|
||||
|
||||
### Runner configuration
|
||||
|
||||
Some things need to be configured in the runner for the interactive web terminal
|
||||
to work:
|
||||
|
||||
- The Runner needs to have
|
||||
[`[session_server]` configured properly](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section).
|
||||
- If you are using a reverse proxy with your GitLab instance, web terminals need to be
|
||||
[enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **[ULTIMATE ONLY]**
|
||||
|
||||
If you have the terminal open and the job has finished with its tasks, the
|
||||
terminal will block the job from finishing for the duration configured in
|
||||
[`[session_server].terminal_max_retention_time`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section)
|
||||
until you close the terminal window.
|
||||
|
||||
NOTE: **Note:** Not all executors are
|
||||
[supported](https://docs.gitlab.com/runner/executors/#compatibility-chart)
|
||||
|
||||
### Web IDE configuration file
|
||||
|
||||
In order to enable the Web IDE terminals you need to create the file
|
||||
`.gitlab/.gitlab-webide.yml` inside the repository's root. This
|
||||
file is fairly similar to the [CI configuration file](../../../ci/yaml/README.md)
|
||||
syntax but with some restrictions:
|
||||
|
||||
- No global blocks can be defined (ie: `before_script` or `after_script`)
|
||||
- Only one job named `terminal` can be added to this file.
|
||||
- Only the keywords `image`, `services`, `tags`, `before_script`, `script`, and
|
||||
`variables` are allowed to be used to configure the job.
|
||||
- To connect to the interactive terminal, the `terminal` job must be still alive
|
||||
and running, otherwise the terminal won't be able to connect to the job's session.
|
||||
By default the `script` keyword has the value `sleep 60` to prevent
|
||||
the job from ending and giving the Web IDE enough time to connect. This means
|
||||
that, if you override the default `script` value, you'll have to add a command
|
||||
which would keep the job running, like `sleep`.
|
||||
|
||||
In the code below there is an example of this configuration file:
|
||||
|
||||
```yaml
|
||||
terminal:
|
||||
before_script:
|
||||
- apt-get update
|
||||
script: sleep 60
|
||||
variables:
|
||||
RAILS_ENV: "test"
|
||||
NODE_ENV: "test"
|
||||
```
|
||||
|
||||
Once the terminal has started, the console will be displayed and we could access
|
||||
the project repository files.
|
||||
|
||||
**Important**. The terminal job is branch dependant. This means that the
|
||||
configuration file used to trigger and configure the terminal will be the one in
|
||||
the selected branch of the Web IDE.
|
||||
|
||||
If there is no configuration file in a branch, an error message will be shown.
|
||||
|
||||
### Running Interactive Terminals in the Web IDE
|
||||
|
||||
If Interactive Terminals are available for the current user, the **Terminal** button
|
||||
will be visible in the right sidebar of the Web IDE. Click this button to open
|
||||
or close the terminal tab.
|
||||
|
||||
Once open, the tab will show the **Start Web Terminal** button. This button may
|
||||
be disabled if the environment is not configured correctly. If so, a status
|
||||
message will describe the issue. Here are some reasons why **Start Web Terminal**
|
||||
may be disabled:
|
||||
|
||||
- `.gitlab/.gitlab-webide.yml` does not exist or is set up incorrectly.
|
||||
- No active private runners are available for the project.
|
||||
|
||||
If active, clicking the **Start Web Terminal** button will load the terminal view
|
||||
and start connecting to the runner's terminal. At any time, the **Terminal** tab
|
||||
can be closed and reopened and the state of the terminal will not be affected.
|
||||
|
||||
When the terminal is started and is successfully connected to the runner, then the
|
||||
runner's shell prompt will appear in the terminal. From here, you can enter
|
||||
commands that will be executed within the runner's environment. This is similar
|
||||
to running commands in a local terminal or through SSH.
|
||||
|
||||
While the terminal is running, it can be stopped by clicking **Stop Terminal**.
|
||||
This will disconnect the terminal and stop the runner's terminal job. From here,
|
||||
click **Restart Terminal** to start a new terminal session.
|
||||
|
||||
### Limitations
|
||||
|
||||
Interactive Terminals is in a beta phase and will continue to be improved upon in upcoming
|
||||
releases. In the meantime, please note that the user is limited to having only one
|
||||
active terminal at a time.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
- If the terminal's text is gray and unresponsive, then the terminal has stopped
|
||||
and it can no longer be used. A stopped terminal can be restarted by clicking
|
||||
**Restart Terminal**.
|
||||
- If the terminal displays **Connection Failure**, then the terminal could not
|
||||
connect to the runner. Please try to stop and restart the terminal. If the
|
||||
problem persists, double check your runner configuration.
|
||||
|
||||
|
||||
[ce]: https://about.gitlab.com/pricing/
|
||||
[ee]: https://about.gitlab.com/pricing/
|
||||
|
|
Loading…
Reference in New Issue