프로젝트 패키지 레지스트리에 Maven 아티팩트를 게시하세요. 그런 다음 의존성으로 사용해야 할 때마다 패키지를 설치할 수 있습니다.

Maven 패키지 관리자 클라이언트가 사용하는 특정 API 엔드포인트에 대한 문서는 Maven API 문서를 참조하세요.

지원 클라이언트:

• mvn. Maven 패키지 빌드 방법을 알아보세요.

• gradle. Gradle 패키지 빌드 방법을 알아보세요.

• sbt.

GitLab 패키지 레지스트리에 게시#

패키지 레지스트리 인증#

패키지를 게시하려면 토큰이 필요합니다. 달성하려는 목표에 따라 다양한 토큰을 사용할 수 있습니다. 자세한 내용은 토큰 관련 안내를 참조하세요.

토큰을 생성하고 이후 과정에서 사용할 수 있도록 저장하세요.

여기에 문서화된 방법 이외의 인증 방법은 사용하지 마세요. 문서화되지 않은 인증 방법은 향후 제거될 수 있습니다.

클라이언트 설정 편집#

HTTP를 통해 Maven 리포지터리에 인증하도록 설정을 업데이트하세요.

사용자 지정 HTTP 헤더#

클라이언트의 설정 파일에 인증 정보를 추가해야 합니다.

mvn

`<name>` 필드는 선택한 토큰과 일치하는 이름으로 지정해야 합니다.

settings.xml 파일에 다음 섹션을 추가하세요.

<settings>
  <servers>
    <server>
      <id>gitlab-maven</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>REPLACE_WITH_NAME</name>
            <value>REPLACE_WITH_TOKEN</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

gradle

`<name>` 필드는 선택한 토큰과 일치하는 이름으로 지정해야 합니다.

GRADLE_USER_HOME 디렉터리에 다음 내용으로 gradle.properties 파일을 생성하세요.

gitLabPrivateToken=REPLACE_WITH_YOUR_TOKEN

build.gradle 파일에 repositories 섹션을 추가하세요.

Groovy DSL 사용:

repositories {
    maven {
        url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven"
        name "GitLab"
        credentials(HttpHeaderCredentials) {
            name = 'REPLACE_WITH_NAME'
            value = gitLabPrivateToken
        }
        authentication {
            header(HttpHeaderAuthentication)
        }
    }
}

Kotlin DSL 사용:

repositories {
    maven {
        url = uri("https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven")
        name = "GitLab"
        credentials(HttpHeaderCredentials::class) {
            name = "REPLACE_WITH_NAME"
            value = findProperty("gitLabPrivateToken") as String?
        }
        authentication {
            create("header", HttpHeaderAuthentication::class)
        }
    }
}

기본 HTTP 인증#

Maven 패키지 레지스트리 인증에 기본 HTTP 인증을 사용할 수도 있습니다.

mvn

settings.xml 파일에 다음 섹션을 추가하세요.

<settings>
  <servers>
    <server>
      <id>gitlab-maven</id>
      <username>REPLACE_WITH_NAME</username>
      <password>REPLACE_WITH_TOKEN</password>
      <configuration>
        <authenticationInfo>
          <userName>REPLACE_WITH_NAME</userName>
          <password>REPLACE_WITH_TOKEN</password>
        </authenticationInfo>
      </configuration>
    </server>
  </servers>
</settings>

gradle

GRADLE_USER_HOME 디렉터리에 다음 내용으로 gradle.properties 파일을 생성하세요.

gitLabPrivateToken=REPLACE_WITH_YOUR_TOKEN

build.gradle에 repositories 섹션을 추가하세요.

Groovy DSL 사용:

repositories {
    maven {
        url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven"
        name "GitLab"
        credentials(PasswordCredentials) {
            username = 'REPLACE_WITH_NAME'
            password = gitLabPrivateToken
        }
        authentication {
            basic(BasicAuthentication)
        }
    }
}

Kotlin DSL 사용:

repositories {
    maven {
        url = uri("https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven")
        name = "GitLab"
        credentials(BasicAuthentication::class) {
            username = "REPLACE_WITH_NAME"
            password = findProperty("gitLabPrivateToken") as String?
        }
        authentication {
            create("basic", BasicAuthentication::class)
        }
    }
}

sbt

SBT 인증은 기본 HTTP 인증을 기반으로 합니다. 이름과 비밀번호를 제공해야 합니다.

이름 필드는 선택한 토큰과 일치하는 이름으로 지정해야 합니다.

sbt를 사용하여 Maven GitLab 패키지 레지스트리에서 패키지를 설치하려면 Maven resolver를 설정해야 합니다. 비공개 또는 내부 프로젝트나 그룹에 접근하는 경우 자격 증명을 설정해야 합니다. resolver와 인증을 설정한 후 프로젝트, 그룹 또는 네임스페이스에서 패키지를 설치할 수 있습니다.

build.sbt에 다음 줄을 추가하세요.

resolvers += ("gitlab" at "<endpoint url>")

credentials += Credentials("GitLab Packages Registry", "<host>", "<name>", "<token>")

이 예시에서:

• <endpoint url>은 엔드포인트 URL입니다. 예시: https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven.

• <host>는 프로토콜 스킴이나 포트 없이 <endpoint url>에 있는 호스트입니다. 예시: gitlab.example.com.

• <name>과 <token>은 이전 표에서 설명합니다.

명명 규칙#

Maven 패키지를 설치하는 데 세 가지 엔드포인트 중 하나를 사용할 수 있습니다. 패키지는 반드시 프로젝트에 게시해야 하지만, 선택하는 엔드포인트에 따라 게시를 위해 pom.xml 파일에 추가하는 설정이 결정됩니다.

세 가지 엔드포인트는 다음과 같습니다:

• 프로젝트: Maven 패키지가 몇 개 없고 동일한 GitLab 그룹에 속하지 않을 때 사용합니다.

• 그룹: 동일한 GitLab 그룹의 다양한 프로젝트에서 패키지를 설치하려는 경우 사용합니다. GitLab은 그룹 내 패키지 이름의 고유성을 보장하지 않습니다. 동일한 패키지 이름과 버전을 가진 두 개의 프로젝트가 있을 수 있습니다. 결과적으로 GitLab은 더 최근의 것을 제공합니다.

• 인스턴스: 다양한 GitLab 그룹이나 자체 네임스페이스에 많은 패키지가 있을 때 사용합니다.

인스턴스 레벨 엔드포인트의 경우, Maven의 pom.xml에서 관련 섹션이 다음과 같이 보여야 합니다:

  <groupId>group-slug.subgroup-slug</groupId>
  <artifactId>project-slug</artifactId>

프로젝트와 동일한 경로를 가진 패키지만 인스턴스 레벨 엔드포인트에 의해 노출됩니다.

엔드포인트 URL#

게시용 설정 파일 편집#

클라이언트의 설정 파일에 게시 세부 정보를 추가해야 합니다.

mvn

선택하는 엔드포인트에 관계없이 다음이 필요합니다:

• distributionManagement 섹션의 프로젝트별 URL.

• repository와 distributionManagement 섹션.

Maven의 pom.xml에서 관련 repository 섹션은 다음과 같아야 합니다:

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url><your_endpoint_url></url>
  </repository>
</repositories>
<distributionManagement>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url>
  </repository>
  <snapshotRepository>
    <id>gitlab-maven</id>
    <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url>
  </snapshotRepository>
</distributionManagement>

• id는 settings.xml에서 정의한 값입니다.

• <your_endpoint_url>은 선택하는 엔드포인트에 따라 다릅니다.

• gitlab.example.com을 도메인 이름으로 바꾸세요.

  gradle

  Gradle을 사용하여 패키지를 게시하려면:

plugins 섹션에 Gradle 플러그인 maven-publish를 추가하세요:

Groovy DSL 사용:

plugins {
    id 'java'
    id 'maven-publish'
}

Kotlin DSL 사용:

plugins {
    java
    `maven-publish`
}

publishing 섹션을 추가하세요:

Groovy DSL 사용:

publishing {
    publications {
        library(MavenPublication) {
            from components.java
        }
    }
    repositories {
        maven {
            url "https://gitlab.example.com/api/v4/projects//packages/maven"
            credentials(HttpHeaderCredentials) {
                name = "REPLACE_WITH_TOKEN_NAME"
                value = gitLabPrivateToken // the variable resides in $GRADLE_USER_HOME/gradle.properties
            }
            authentication {
                header(HttpHeaderAuthentication)
            }
        }
    }
}

Kotlin DSL 사용:

publishing {
    publications {
        create("library") {
            from(components["java"])
        }
    }
    repositories {
        maven {
            url = uri("https://gitlab.example.com/api/v4/projects//packages/maven")
            credentials(HttpHeaderCredentials::class) {
                name = "REPLACE_WITH_TOKEN_NAME"
                value =
                    findProperty("gitLabPrivateToken") as String? // the variable resides in $GRADLE_USER_HOME/gradle.properties
            }
            authentication {
                create("header", HttpHeaderAuthentication::class)
            }
        }
    }
}

패키지 게시#

`DeployAtEnd` 옵션을 사용하면 `400 bad request {"message":"Validation failed: Name has already been taken"}` 오류와 함께 업로드가 거부될 수 있습니다. 자세한 내용은 [이슈 424238](https://gitlab.com/gitlab-org/gitlab/-/issues/424238)을 참조하세요.

인증을 설정하고 게시용 엔드포인트를 선택한 후, 프로젝트에 Maven 패키지를 게시하세요.

mvn

Maven을 사용하여 패키지를 게시하려면:

mvn deploy

배포에 성공하면 빌드 성공 메시지가 표시됩니다:

...
[INFO] BUILD SUCCESS
...

패키지가 올바른 위치에 게시되었음을 메시지에서 확인할 수 있습니다:

Uploading to gitlab-maven: https://example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.jar

gradle

publish 태스크를 실행하세요:

gradle publish

프로젝트의 Packages and registries 페이지로 이동하여 게시된 패키지를 확인하세요.

sbt

`build.sbt` 파일에서 `publishTo` 설정을 구성하세요:

publishTo := Some("gitlab" at "<endpoint url>")

자격 증명이 올바르게 참조되었는지 확인하세요. 자세한 내용은 sbt 문서를 참조하세요.

sbt를 사용하여 패키지를 게시하려면:

sbt publish

배포에 성공하면 빌드 성공 메시지가 표시됩니다:

[success] Total time: 1 s, completed Jan 28, 2020 12:08:57 PM

패키지가 올바른 위치에 게시되었는지 성공 메시지를 확인하세요:

[info]  published my-project_2.12 to https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/my-project_2.12/0.1.1-SNAPSHOT/my-project_2.12-0.1.1-SNAPSHOT.pom

게시하기 전에 Maven 패키지를 보호하면 `403 Forbidden` 오류와 `Authorization failed` 오류 메시지와 함께 패키지가 거부됩니다.

게시할 때 Maven 패키지가 보호되어 있지 않은지 확인하세요. 패키지 보호 규칙에 대한 자세한 내용은 패키지 보호 방법을 참조하세요.

패키지 설치#

GitLab 패키지 레지스트리에서 패키지를 설치하려면 원격 설정 및 인증을 구성해야 합니다. 완료되면 프로젝트, 그룹 또는 네임스페이스에서 패키지를 설치할 수 있습니다.

동일한 이름과 버전의 패키지가 여러 개 있는 경우, 패키지를 설치하면 가장 최근에 게시된 패키지가 검색됩니다.

mvn

`mvn install`을 사용하여 패키지를 설치하려면:

- 프로젝트 pom.xml 파일에 의존성을 수동으로 추가하세요. 앞서 만든 예시를 추가하려면 XML은 다음과 같습니다:

<dependency>
  <groupId>com.mycompany.mydepartment</groupId>
  <artifactId>my-project</artifactId>
  <version>1.0-SNAPSHOT</version>
</dependency>

프로젝트에서 다음을 실행하세요:

mvn install

패키지 레지스트리에서 패키지를 다운로드하고 있음을 메시지에서 확인할 수 있습니다:

Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom

Maven dependency:get 명령을 직접 사용하여 패키지를 설치할 수도 있습니다.

프로젝트 디렉터리에서 다음을 실행하세요:

mvn dependency:get -Dartifact=com.nickkipling.app:nick-test-app:1.1-SNAPSHOT -DremoteRepositories=gitlab-maven::::<gitlab endpoint url>  -s <path to settings.xml>

<gitlab endpoint url>은 GitLab 엔드포인트의 URL입니다.

• <path to settings.xml>은 인증 정보가 포함된 settings.xml 파일의 경로입니다.

  gitlab-maven 명령과 settings.xml 파일의 리포지터리 ID가 일치해야 합니다.

  패키지 레지스트리에서 패키지를 다운로드하고 있음을 메시지에서 확인할 수 있습니다:

Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom

gradle

`gradle`을 사용하여 패키지를 설치하려면:

- build.gradle의 dependencies 섹션에 의존성을 추가하세요:

Groovy DSL 사용:

dependencies {
    implementation 'com.mycompany.mydepartment:my-project:1.0-SNAPSHOT'
}

Kotlin DSL 사용:

dependencies {
    implementation("com.mycompany.mydepartment:my-project:1.0-SNAPSHOT")
}

프로젝트에서 다음을 실행하세요:

gradle build

sbt

`sbt`를 사용하여 패키지를 설치하려면:

- build.sbt에 인라인 의존성을 추가하세요:

libraryDependencies += "com.mycompany.mydepartment" % "my-project" % "8.4"

프로젝트에서 다음을 실행하세요:

sbt update

Maven 패키지 프록시 다운로드#

히스토리

• GitLab 17.8에서 도입됨.

GitLab Maven 패키지 레지스트리는 원격 포함 체크섬을 사용합니다. 파일을 다운로드할 때 레지스트리는 파일을 프록시하고 단일 요청으로 파일과 관련 체크섬을 Maven 클라이언트에 전송합니다.

최신 Maven 클라이언트에서 원격 포함 체크섬을 사용하면:

• 클라이언트에서 GitLab Maven 패키지 레지스트리로의 웹 요청 수가 줄어듭니다.

• GitLab 인스턴스의 부하가 감소합니다.

• 클라이언트 명령 실행 시간이 개선됩니다.

기술적 제약으로 인해 오브젝트 스토리지를 사용할 때 Maven 패키지 레지스트리는 packages에 대한 오브젝트 스토리지 설정의 프록시 다운로드 설정을 무시합니다. 대신 Maven 패키지 레지스트리 다운로드에 대해 프록시 다운로드가 항상 활성화됩니다.

오브젝트 스토리지를 사용하지 않는 경우 이 동작은 인스턴스에 영향을 미치지 않습니다.

Maven 패키지를 위한 CI/CD 통합#

CI/CD를 사용하여 Maven 패키지를 자동으로 빌드, 테스트 및 게시할 수 있습니다. 이 섹션의 예시는 다음과 같은 시나리오를 다룹니다:

• 멀티 모듈 프로젝트

• 버전 릴리즈

• 조건부 게시

• 코드 품질 및 보안 스캔과의 통합

이 예시들을 특정 프로젝트 필요에 맞게 조정하고 결합할 수 있습니다.

Maven 버전, Java 버전 및 기타 세부 사항을 프로젝트 요구사항에 맞게 조정하세요. 또한 GitLab 패키지 레지스트리에 게시하기 위한 필요한 자격 증명과 설정을 올바르게 구성했는지 확인하세요.

기본 Maven 패키지 빌드 및 게시#

이 예시는 Maven 패키지를 빌드하고 게시하는 파이프라인을 구성합니다:

default:
  image: maven:3.8.5-openjdk-17
  cache:
    paths:
      - .m2/repository/
      - target/

variables:
  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

stages:
  - build
  - test
  - publish

build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS compile

test:
  stage: test
  script:
    - mvn $MAVEN_CLI_OPTS test

publish:
  stage: publish
  script:
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

병렬 job을 사용한 멀티 모듈 Maven 프로젝트#

여러 모듈이 있는 대규모 프로젝트의 경우 병렬 job을 사용하여 빌드 프로세스를 가속화할 수 있습니다:

default:
  image: maven:3.8.5-openjdk-17
  cache:
    paths:
      - .m2/repository/
      - target/

variables:
  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

stages:
  - build
  - test
  - publish

build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS compile

test:
  stage: test
  parallel:
    matrix:
      - MODULE: [module1, module2, module3]
  script:
    - mvn $MAVEN_CLI_OPTS test -pl $MODULE

publish:
  stage: publish
  script:
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

태그를 사용한 버전 릴리즈#

이 예시는 태그가 푸시될 때 버전 릴리즈를 생성합니다:

default:
  image: maven:3.8.5-openjdk-17
  cache:
    paths:
      - .m2/repository/
      - target/

variables:
  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

stages:
  - build
  - test
  - publish
  - release

build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS compile

test:
  stage: test
  script:
    - mvn $MAVEN_CLI_OPTS test

publish:
  stage: publish
  script:
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

release:
  stage: release
  script:
    - mvn versions:set -DnewVersion=${CI_COMMIT_TAG}
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_TAG

변경 사항에 따른 조건부 게시#

이 예시는 특정 파일이 변경되었을 때만 패키지를 게시합니다:

default:
  image: maven:3.8.5-openjdk-17
  cache:
    paths:
      - .m2/repository/
      - target/

variables:
  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

stages:
  - build
  - test
  - publish

build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS compile

test:
  stage: test
  script:
    - mvn $MAVEN_CLI_OPTS test

publish:
  stage: publish
  script:
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        - pom.xml
        - src/**/*

코드 품질 및 보안 스캔과의 통합#

이 예시는 파이프라인에 코드 품질 검사와 보안 스캔을 통합합니다:

default:
  image: maven:3.8.5-openjdk-17
  cache:
    paths:
      - .m2/repository/
      - target/

variables:
  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Code-Quality.gitlab-ci.yml

stages:
  - build
  - test
  - quality
  - publish

build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS compile

test:
  stage: test
  script:
    - mvn $MAVEN_CLI_OPTS test

code_quality:
  stage: quality

sast:
  stage: quality

publish:
  stage: publish
  script:
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

유용한 힌트#

동일한 이름이나 버전의 패키지 게시#

기존 패키지와 동일한 이름과 버전을 가진 패키지를 게시하면 새 패키지 파일이 기존 패키지에 추가됩니다. UI 또는 API를 사용하여 기존 패키지의 이전 에셋에 계속 접근하고 볼 수 있습니다.

이전 패키지 버전을 삭제하려면 Packages API 또는 UI를 사용하는 것을 고려하세요.

중복 Maven 패키지 허용 안 함#

히스토리

• GitLab 15.0에서 Developer에서 Maintainer로 필요 권한이 변경됨.

• GitLab 17.0에서 Maintainer에서 Owner로 필요 권한이 변경됨.

사용자가 중복 Maven 패키지를 게시하는 것을 방지하려면 GraphQL API 또는 UI를 사용할 수 있습니다.

UI에서:

• 상단 바에서 Search or go to를 선택하고 그룹을 찾으세요.

• 왼쪽 사이드바에서 Settings > Packages and registries를 선택하세요.

• Duplicate packages 표의 Maven 행에서 Allow duplicates 토글을 끄세요.

• 선택 사항. Exceptions 텍스트 상자에 허용할 패키지 이름 및 버전과 일치하는 정규 표현식을 입력하세요.

  Allow duplicates가 켜져 있는 경우 Exceptions 텍스트 상자에서 중복을 허용하지 않아야 하는 패키지 이름과 버전을 지정할 수 있습니다.

  변경 사항은 자동으로 저장됩니다.

Maven Central로 요청 전달#

히스토리

• GitLab 15.4에서 maven_central_request_forwarding이라는 플래그와 함께 도입됨. 기본적으로 비활성화됨.

• GitLab 17.0에서 Maintainer에서 Owner로 필요 권한이 변경됨.

  이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 히스토리를 참조하세요.

  패키지 레지스트리에서 Maven 패키지를 찾을 수 없는 경우 요청이 Maven Central로 전달됩니다.

기능 플래그가 활성화되면 관리자는 Continuous Integration 설정에서 이 동작을 비활성화할 수 있습니다.

Maven 전달은 프로젝트 레벨 및 그룹 레벨 엔드포인트만으로 제한됩니다. 인스턴스 레벨 엔드포인트는 해당 규칙을 따르지 않는 패키지에 사용하지 못하도록 하는 명명 제한이 있으며, 공급망 스타일 공격에 대한 보안 위험도 너무 높습니다.

mvn을 위한 추가 설정#

mvn을 사용할 때 GitLab에서 Maven Central의 패키지를 요청하도록 Maven 프로젝트를 설정하는 다양한 방법이 있습니다. Maven 리포지터리는 특정 순서로 쿼리됩니다. 기본적으로 Maven Central은 보통 Super POM을 통해 먼저 확인되므로, GitLab이 maven-central보다 먼저 쿼리되도록 구성해야 합니다.

모든 패키지 요청이 Maven Central 대신 GitLab으로 전송되도록 하려면 settings.xml에 <mirror> 섹션을 추가하여 Maven Central을 중앙 리포지터리로 재정의할 수 있습니다:

<settings>
  <servers>
    <server>
      <id>central-proxy</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Private-Token</name>
            <value><personal_access_token></value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
  <mirrors>
    <mirror>
      <id>central-proxy</id>
      <name>GitLab proxy of central repo</name>
      <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>

GitLab CI/CD로 Maven 패키지 생성#

Maven용 패키지 레지스트리를 사용하도록 리포지터리를 구성한 후 GitLab CI/CD가 자동으로 새 패키지를 빌드하도록 구성할 수 있습니다.

mvn

기본 브랜치가 업데이트될 때마다 새 패키지를 생성할 수 있습니다.

- Maven의 settings.xml 파일 역할을 하는 ci_settings.xml 파일을 생성하세요.

pom.xml 파일에서 정의한 것과 동일한 ID를 가진 server 섹션을 추가하세요. 예를 들어 gitlab-maven을 ID로 사용하세요:

<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>${CI_JOB_TOKEN}</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

pom.xml 파일에 다음이 포함되어 있는지 확인하세요. 이 예시와 같이 Maven이 사전 정의된 CI/CD 변수를 사용하도록 하거나, 서버의 호스트명과 프로젝트 ID를 하드코딩할 수 있습니다.

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url>
  </repository>
</repositories>
<distributionManagement>
  <repository>
    <id>gitlab-maven</id>
    <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url>
  </repository>
  <snapshotRepository>
    <id>gitlab-maven</id>
    <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url>
  </snapshotRepository>
</distributionManagement>

.gitlab-ci.yml 파일에 deploy job을 추가하세요:

deploy:
  image: maven:3.6-jdk-11
  script:
    - 'mvn deploy -s ci_settings.xml'
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

해당 파일들을 리포지터리에 푸시하세요.

다음번 deploy job이 실행되면 ci_settings.xml이 사용자의 홈 위치로 복사됩니다. 이 예시에서:

• job이 Docker 컨테이너에서 실행되므로 사용자는 root입니다.

• Maven은 설정된 CI/CD 변수를 사용합니다.

  gradle

  기본 브랜치가 업데이트될 때마다 패키지를 생성할 수 있습니다.

Gradle의 CI job 토큰으로 인증하세요.

.gitlab-ci.yml 파일에 deploy job을 추가하세요:

deploy:
  image: gradle:6.5-jdk11
  script:
    - 'gradle publish'
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

파일들을 리포지터리에 커밋하세요.

파이프라인이 성공하면 Maven 패키지가 생성됩니다.

버전 유효성 검사#

버전 문자열은 다음 정규식을 사용하여 유효성을 검사합니다.

\A(?!.*\.\.)[\w+.-]+\z

이 정규 표현식 편집기에서 정규식을 실험하고 버전 문자열을 시도해볼 수 있습니다.

스냅샷 및 릴리즈 배포에 다른 설정 사용#

스냅샷과 릴리즈에 다른 URL이나 설정을 사용하려면:

• pom.xml 파일의 <distributionManagement> 섹션에서 별도의 <repository>와 <snapshotRepository> 요소를 정의하세요.

유용한 Maven 명령줄 옵션#

GitLab CI/CD에서 태스크를 수행할 때 사용할 수 있는 몇 가지 Maven 명령줄 옵션이 있습니다.

파일 전송 진행률로 CI 로그를 읽기 어려울 수 있습니다. 옵션 -ntp,--no-transfer-progress는 3.6.1에서 추가되었습니다. 또는 -B,--batch-mode 또는 더 낮은 수준의 로깅 변경을 살펴보세요.

pom.xml 파일의 위치를 지정하세요 (-f,--file):

package:
  script:
    - 'mvn --no-transfer-progress -f helloworld/pom.xml package'

기본 위치 대신 사용자 설정을 찾을 위치를 지정하세요 (-s,--settings). -gs,--global-settings 옵션도 있습니다:

package:
  script:
    - 'mvn -s settings/ci.xml package'

지원되는 CLI 명령#

GitLab Maven 리포지터리는 다음 CLI 명령을 지원합니다:

mvn

• mvn deploy: 패키지 레지스트리에 패키지를 게시합니다.

• mvn install: Maven 프로젝트에 지정된 패키지를 설치합니다.

• mvn dependency:get: 특정 패키지를 설치합니다.

  gradle

• gradle publish: 패키지 레지스트리에 패키지를 게시합니다.

• gradle build: 프로젝트를 어셈블하고 테스트합니다.

문제 해결#

GitLab에서 Maven 패키지를 사용하는 동안 문제가 발생할 수 있습니다. 많은 일반적인 문제를 해결하려면 다음 단계를 시도해보세요:

• 인증 확인 - 인증 토큰이 올바르고 만료되지 않았는지 확인하세요.

• 권한 확인 - 패키지를 게시하거나 설치하는 데 필요한 권한이 있는지 확인하세요.

• Maven 설정 유효성 검사 - 올바른 설정을 위해 settings.xml 파일을 다시 확인하세요.

• GitLab CI/CD 로그 검토 - CI/CD 문제의 경우 오류 메시지를 위해 job 로그를 주의 깊게 검토하세요.

• 올바른 엔드포인트 URL 확인 - 프로젝트 또는 그룹에 올바른 엔드포인트 URL을 사용하고 있는지 확인하세요.

• mvn 명령에 -s 옵션 사용 - 항상 -s 옵션과 함께 Maven 명령을 실행하세요. 예: mvn package -s settings.xml. 이 옵션 없이는 인증 설정이 적용되지 않아 Maven이 패키지를 찾지 못할 수 있습니다.

캐시 지우기#

성능 향상을 위해 클라이언트는 패키지 관련 파일을 캐시합니다. 문제가 발생하면 다음 명령으로 캐시를 지우세요:

mvn

rm -rf ~/.m2/repository

gradle

rm -rf ~/.gradle/caches # Or replace ~/.gradle with your custom GRADLE_USER_HOME

네트워크 추적 로그 검토#

Maven 리포지터리에 문제가 있는 경우 네트워크 추적 로그를 검토하는 것이 좋습니다. 네트워크 추적 로그를 검토하면 Maven 클라이언트가 기본적으로 포함하지 않는 더 자세한 오류 메시지를 얻을 수 있습니다.

예를 들어, PAT 토큰으로 로컬에서 mvn deploy를 실행하고 다음 옵션을 사용해 보세요:

mvn deploy \
-Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient=trace \
-Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient.wire=trace

이 옵션을 설정하면 모든 네트워크 요청이 기록되고 많은 양의 출력이 생성됩니다.

Maven 설정 확인#

CI/CD 내에서 settings.xml 파일과 관련된 문제가 발생하면 유효한 설정을 확인하기 위해 추가 스크립트 태스크나 job을 추가해 보세요.

help 플러그인은 환경 변수를 포함한 시스템 속성도 제공할 수 있습니다:

mvn-settings:
  script:
    - 'mvn help:effective-settings'

package:
  script:
    - 'mvn help:system'
    - 'mvn package'

패키지 게시 시 401 Unauthorized 오류#

이는 일반적으로 인증 문제를 나타냅니다. 다음을 확인하세요:

• 인증 토큰이 유효하고 만료되지 않았는지 확인하세요.

• 올바른 토큰 유형(personal access token, deploy token 또는 CI job 토큰)을 사용하고 있는지 확인하세요.

• 토큰에 필요한 권한(api, read_api 또는 read_repository)이 있는지 확인하세요.

• Maven 프로젝트의 경우 mvn 명령에 -s 옵션을 사용하고 있는지 확인하세요 (예: mvn deploy -s settings.xml). 이 옵션 없이는 Maven이 settings.xml 파일의 인증 설정을 적용하지 않아 인증 오류가 발생합니다.

"Validation failed: Version is invalid" 메시지와 함께 400 Bad Request 오류#

GitLab은 버전 문자열에 특정 요구사항이 있습니다. 버전이 다음 형식을 따르는지 확인하세요:

^(?!.*\.\.)(?!.*\.$)[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*(\+[0-9A-Za-z-]+)?$

예를 들어 "1.0.0", "1.0-SNAPSHOT", "1.0.0-alpha"는 유효하지만 "1..0" 또는 "1.0."는 유효하지 않습니다.

패키지 게시 시 403 Forbidden 오류#

Authorization failed 메시지와 함께 403 Forbidden 오류는 일반적으로 인증 또는 권한 문제를 나타냅니다. 다음을 확인하세요:

• 올바른 토큰 유형(personal access token, deploy token 또는 CI/CD job 토큰)을 사용하고 있는지 확인하세요. 자세한 내용은 패키지 레지스트리 인증을 참조하세요.

• 토큰에 필요한 권한이 있는지 확인하세요. Developer, Maintainer 또는 Owner 권한이 있는 사용자만 패키지를 게시할 수 있습니다. 자세한 내용은 GitLab 권한을 참조하세요.

• 게시하려는 패키지가 푸시 보호 규칙으로 보호되어 있지 않은지 확인하세요. 패키지 보호 규칙에 대한 자세한 내용은 패키지 보호 방법을 참조하세요.

게시 시 아티팩트가 이미 존재한다는 오류#

이 오류는 이미 존재하는 패키지 버전을 게시하려고 할 때 발생합니다. 해결하려면:

• 게시 전에 패키지 버전을 올리세요.

• SNAPSHOT 버전을 사용하는 경우 설정에서 SNAPSHOT 덮어쓰기를 허용하고 있는지 확인하세요.

게시한 패키지가 UI에 표시되지 않음#

방금 패키지를 게시했다면 표시되는 데 잠시 시간이 걸릴 수 있습니다. 여전히 표시되지 않으면:

• 패키지를 볼 수 있는 필요한 권한이 있는지 확인하세요.

• CI/CD 로그 또는 Maven 출력을 검토하여 패키지가 성공적으로 게시되었는지 확인하세요.

• 올바른 프로젝트 또는 그룹에서 확인하고 있는지 확인하세요.

Maven 리포지터리 의존성 충돌#

의존성 충돌은 다음과 같이 해결할 수 있습니다:

• pom.xml에서 버전을 명시적으로 정의하세요.

• Maven의 dependency management 섹션을 사용하여 버전을 제어하세요.

• <exclusions> 태그를 사용하여 충돌하는 전이 의존성을 제외하세요.

요청된 대상에 대한 유효한 인증 경로를 찾을 수 없는 오류#

이는 일반적으로 SSL 인증서 문제입니다. 해결하려면:

• JDK가 GitLab 서버의 SSL 인증서를 신뢰하는지 확인하세요.

• 자체 서명 인증서를 사용하는 경우 JDK의 truststore에 추가하세요.

• 최후의 수단으로 Maven 설정에서 SSL 검증을 비활성화할 수 있습니다. 프로덕션 환경에서는 권장하지 않습니다.

파이프라인 오류에서 prefix pipeline에 대한 플러그인을 찾을 수 없음#

이는 보통 Maven이 플러그인을 찾을 수 없음을 의미합니다. 해결하려면:

• pom.xml에 플러그인이 올바르게 정의되어 있는지 확인하세요.

• CI/CD 설정이 올바른 Maven 설정 파일을 사용하고 있는지 확인하세요.

• 파이프라인이 필요한 모든 리포지터리에 접근할 수 있는지 확인하세요.