패키지 레지스트리의 Composer 패키지

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated Status: Beta
  • GitLab 13.2에서 도입되었습니다.
  • GitLab Premium에서 GitLab 13.3으로 이동되어 GitLab Free로 이동되었습니다.
  • Composer 2.0 지원이 GitLab 13.10에서 추가되었습니다.
  • Deploy 토큰 지원이 GitLab 14.6에서 추가되었습니다.
caution
GitLab의 Composer 패키지 레지스트리는 제한된 기능으로 인해 프로덕션 용도로 사용하기에 준비되지 않았으며 개발 중입니다. 이 epic에서 나머지 작업과 프로덕션 준비까지의 시간에 대한 상세 정보를 확인할 수 있습니다.

프로젝트의 패키지 레지스트리에 Composer 패키지를 게시하세요. 그런 다음 이를 의존성으로 사용해야 하는 경우 필요할 때 패키지를 설치하십시오.

Composer 클라이언트가 사용하는 특정 API 엔드포인트에 대한 문서는 Composer API 문서를 참조하세요.

Composer v2.0를 권장합니다. Composer v1.0은 지원되지만 매우 많은 패키지가 있는 그룹에서 작업할 때 성능이 떨어집니다.

Composer 패키지를 작성하는 방법을 알아보세요.

API를 사용하여 Composer 패키지 게시

Composer 패키지를 패키지 레지스트리에 게시하여 프로젝트에 액세스할 수 있는 모든 사람이 패키지를 의존성으로 사용할 수 있도록 합니다.

필수 조건:

  • GitLab 리포지터리의 패키지입니다. Composer 패키지는 Composer 사양에 따라 버전이 지정되어야 합니다. 버전이 유효하지 않으면 (1.0.0.0과 같이 세 개의 점이 있는 경우) 게시할 때 오류(Validation failed: Version is invalid)가 발생합니다.
  • 프로젝트 루트 디렉터리에 유효한 composer.json 파일이 있어야 합니다.
  • GitLab 리포지터리에서 패키지 기능이 활성화되어 있어야 합니다.
  • 프로젝트 개요 페이지에 표시된 프로젝트 ID가 있어야 합니다.
  • 다음 토큰 유형 중 하나:

개인 액세스 토큰을 사용하여 패키지를 게시하려면:

  • POST 요청을 Packages API로 보냅니다.

    예: 

    curl --data tag=<tag> "https://__token__:<personal-access-token>@gitlab.example.com/api/v4/projects/<project_id>/packages/composer"
    • <personal-access-token>은 개인 액세스 토큰입니다.
    • <project_id>는 프로젝트 ID입니다.
    • <tag>는 게시할 버전의 Git 태그 이름입니다. 브랜치를 게시하려면 tag=<tag> 대신 branch=<branch>를 사용합니다.

배포 토큰을 사용하여 패키지를 게시하려면:

  • POST 요청을 Packages API로 보냅니다.

    예: 

    curl --data tag=<tag> --header "Deploy-Token: <deploy-token>" "https://gitlab.example.com/api/v4/projects/<project_id>/packages/composer"
    • <deploy-token>은 배포 토큰입니다.
    • <project_id>는 프로젝트 ID입니다.
    • <tag>는 게시할 버전의 Git 태그 이름입니다. 브랜치를 게시하려면 tag=<tag> 대신 branch=<branch>를 사용합니다.

Deploy > Package Registry로 이동하여 게시된 패키지를 확인할 수 있습니다.

CI/CD를 사용하여 Composer 패키지 게시

CI/CD 프로세스의 일환으로 Composer 패키지를 패키지 레지스트리에 게시할 수 있습니다.

  1. .gitlab-ci.yml 파일에 CI_JOB_TOKEN을 지정하세요: 

    stages:
  - deploy
   
deploy:
  stage: deploy
  script:
    - apk add curl
    - 'curl --header "Job-Token: $CI_JOB_TOKEN" --data tag=<tag> "${CI_API_V4_URL}/projects/$CI_PROJECT_ID/packages/composer"'
  environment: production

  2. 파이프라인을 실행합니다.

게시된 패키지를 보려면 Deploy > Package Registry로 이동하여 Composer 탭을 선택합니다.

CI/CD 템플릿 사용

.gitlab-ci.yml 템플릿으로 더 자세한 Composer CI/CD 파일도 사용할 수 있습니다:

  1. 왼쪽 사이드바에서 프로젝트 개요를 선택합니다.
  2. 파일 디렉터리 위에서 CI/CD 설정을 선택합니다. 이 버튼을 사용할 수 없는 경우 CI/CD 구성을 선택한 다음 편집을 선택합니다.
  3. 템플릿 적용 디렉터리에서 Composer를 선택합니다.
caution
기존 CI/CD 파일을 덮어쓰지 않으려면 저장하지 마십시오.

동일한 이름 또는 버전으로 패키지 게시

게시할 때:

  • 동일한 패키지에 다른 데이터를 게시하면 기존 패키지가 덮어씁니다.
  • 동일한 패키지에 동일한 데이터를 게시하면 400 Bad request 오류가 발생합니다.

Composer 패키지 설치

패키지 레지스트리에서 패키지를 설치하여 이를 의존성으로 사용할 수 있습니다.

필수 조건:

  • 패키지가 패키지 레지스트리에 있어야 합니다.
  • 패키지 레지스트리가 패키지를 게시하는 프로젝트에서 활성화되어 있어야 합니다.
  • 그룹의 홈 페이지에 있는 그룹 ID가 있어야 합니다.
  • 다음 토큰 유형 중 하나:

패키지를 설치하려면:

  1. 패키지 레지스트리 URL, 패키지 이름 및 설치하려는 버전을 프로젝트의 composer.json 파일에 추가하세요:

    • 그룹에 대한 패키지 레지스트리에 연결합니다: 
    composer config repositories.<group_id> composer https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/packages.json
    • 필요한 패키지 버전을 설정합니다: 
    composer require <package_name>:<version>

    composer.json 파일에 결과: 

    {
  ...
  "repositories": {
    "<group_id>": {
      "type": "composer",
      "url": "https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/packages.json"
    },
    ...
  },
  "require": {
    ...
    "<package_name>": "<version>"
  },
  ...
}

    이 명령을 사용하여 설정을 취소할 수 있습니다: 

    composer config --unset repositories.<group_id>
    • <group_id>는 그룹 ID입니다.
    • 패키지 이름은 패키지의 composer.json 파일에서 정의된 이름입니다.
    • 버전은 패키지 버전입니다.

  2. GitLab 자격 증명이 포함된 auth.json 파일을 만드세요:

    개인 액세스 토큰을 사용하는 경우: 

    composer config gitlab-token.<DOMAIN-NAME> <personal_access_token>

    auth.json 파일에 결과: 

    {
  ...
  "gitlab-token": {
    "<DOMAIN-NAME>": "<personal_access_token>",
    ...
  }
}

    배포 토큰을 사용하는 경우: 

    composer config gitlab-token.<DOMAIN-NAME> <deploy_token_username> <deploy_token>

    auth.json 파일에 결과: 

    {
  ...
  "gitlab-token": {
    "<DOMAIN-NAME>": {
      "username": "<deploy_token_username>",
      "token": "<deploy_token>",
    ...
  }
}

    CI/CD 작업 토큰을 사용하는 경우: 

    composer config -- gitlab-token.<DOMAIN-NAME> gitlab-ci-token "${CI_JOB_TOKEN}"

    auth.json 파일에 결과: 

    {
  ...
  "gitlab-token": {
    "<DOMAIN-NAME>": {
      "username": "gitlab-ci-token",
      "token": "<ci-job-token>",
    ...
  }
}

    이 명령을 사용하여 설정을 취소할 수 있습니다: 

    composer config --unset --auth gitlab-token.<DOMAIN-NAME>
    • <DOMAIN-NAME>은 GitLab 인스턴스 URL인 gitlab.com 또는 gitlab.example.com입니다.
    • api 범위로 설정된 <personal_access_token> 또는 read_package_registry 및/또는 write_package_registry 범위로 설정된 <deploy_token>을 사용합니다.

  3. GitLab Self-managed 인스턴스인 경우 composer.json에 gitlab-domains을 추가하세요. 

    composer config gitlab-domains gitlab01.example.com gitlab02.example.com

    composer.json 파일에 결과: 

    {
  ...
  "repositories": [
    { "type": "composer", "url": "https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/packages.json" }
  ],
  "config": {
    ...
    "gitlab-domains": ["gitlab01.example.com", "gitlab02.example.com"]
  },
  "require": {
    ...
    "<package_name>": "<version>"
  },
  ...
}

    이 명령을 사용하여 설정을 취소할 수 있습니다: 

    composer config --unset gitlab-domains
    note
    GitLab.com에서는 Composer가 기본적으로 auth.json의 GitLab 토큰을 비공개 토큰으로 사용합니다. composer.json에서 gitlab-domains 정의가 없으면 Composer는 기본적으로 GitLab 토큰을 기본 인증으로 사용하는데, 토큰이 유저이름으로 사용되고 비밀번호는 비어 있는 상태입니다. 결과적으로 401 오류가 발생합니다.

  4. composer.json 및 auth.json 파일을 구성한 후 다음을 실행하여 패키지를 설치할 수 있습니다: 

    composer update

    또는 단일 패키지를 설치하려면: 

    composer req <package-name>:<package-version>
caution
절대로 auth.json 파일을 리포지터리에 커밋하지 마십시오. CI/CD 작업에서 패키지를 설치하려면 액세스 토큰을 GitLab CI/CD 변수 또는 HashiCorp Vault에 저장하는 composer config 도구를 사용하는 방법을 고려하십시오.

소스로부터 설치하기

Git 리포지터리를 직접 끌어와서 소스로부터 설치할 수 있습니다. 이를 위해 다음 중 하나를 사용하세요:

  • --prefer-source 옵션을 사용합니다: 

    composer update --prefer-source

  • composer.json에서 config 키 아래의 preferred-install 필드를 사용합니다(링크): 

    {
  ...
  "config": {
    "preferred-install": {
      "<package name>": "source"
    }
  }
  ...
 }

SSH 액세스

플래그: Self-managed GitLab에서는 기본적으로 이 기능을 사용할 수 있습니다. 프로젝트 단위로 기능을 숨기려면 관리자가 composer_use_ssh_source_urls라는 피처 플래그를 비활성화할 수 있습니다. GitLab.com 및 GitLab Dedicated에서 이 기능을 사용할 수 있습니다.

소스로부터 설치하는 경우, composer는 프로젝트의 Git 리포지터리로의 접근을 구성합니다. 프로젝트의 가시성에 따라 액세스 유형이 다릅니다:

SSH 키를 사용하여 CI/CD 작업에서 ssh Git URL에 액세스할 수 있습니다.

배포 토큰 사용하기

Composer 패키지는 그룹 수준에서 액세스되지만, 그룹 또는 프로젝트 배포 토큰을 사용해 액세스할 수 있습니다:

  • 그룹 배포 토큰은 해당 그룹이나 하위 그룹의 프로젝트에 발행된 모든 패키지에 액세스할 수 있습니다.
  • 프로젝트 배포 토큰은 해당 프로젝트에 발행된 패키지에만 액세스할 수 있습니다.

문제 해결

캐싱

성능을 향상시키기 위해 Composer는 패키지 관련 파일을 캐시에 저장합니다. Composer는 자체적으로 데이터를 제거하지 않습니다. 새 패키지가 설치될수록 캐시가 증가합니다. 문제가 발생하면 다음 명령으로 캐시를 지울 수 있습니다. 

composer clearcache

composer install 사용 시 인증 요구사항

GitLab 14.9 이전에는 생성된 composer.lock이 있으면 composer install에 대한 인증이 필요하지 않았습니다. composer.lock을 커밋했다면 자격 증명을 설정하지 않고 CI에서 composer install을 수행할 수 있었습니다.

GitLab 14.10 이후에는 패키지 아카이브 다운로드 엔드포인트를 사용할 때 인증이 필요합니다. composer install을 사용하는 동안 자격 증명 프롬프트가 표시되는 경우 composer 패키지 설치 섹션의 지침을 따라 auth.json 파일을 만듭니다.

The file composer.json was not found로 게시가 실패하는 경우

The file composer.json was not found라는 오류가 표시될 수 있습니다.

이 문제는 패키지 게시를 위한 구성 요구 사항이 충족되지 않았을 때 발생합니다.

해당 오류를 해결하려면 프로젝트 루트 디렉터리에 composer.json 파일을 커밋하세요.

지원되는 CLI 명령어

GitLab Composer 리포지터리에서는 다음과 같은 Composer CLI 명령어를 지원합니다:

  • composer install: Composer 의존성 설치
  • composer update: Composer 의존성의 최신 버전 설치