프로젝트의 패키지 레지스트리에 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.
• 다음 토큰 유형 중 하나:
  • 범위가 api로 설정된 개인 액세스 토큰.
  • 범위가 write_package_registry로 설정된 배포 토큰.

개인 액세스 토큰으로 패키지를 게시하려면:

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

  예를 들어 curl을 사용할 수 있습니다:

  curl --fail-with-body --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>를 사용합니다.

배포 토큰으로 패키지를 게시하려면:

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

  예를 들어 curl을 사용할 수 있습니다:

  curl --fail-with-body --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>를 사용합니다.

게시된 패키지는 배포 > 패키지 레지스트리로 이동하고 Composer 탭을 선택하여 볼 수 있습니다.

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

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

1. .gitlab-ci.yml 파일에 CI_JOB_TOKEN을 지정합니다:

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

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

게시된 패키지를 보려면 배포 > 패키지 레지스트리로 이동하고 Composer 탭을 선택합니다.

CI/CD 템플릿 사용#

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

1. 왼쪽 사이드바에서 프로젝트 개요를 선택합니다.
2. 파일 목록 위에서 CI/CD 설정을 선택합니다. 이 버튼을 사용할 수 없는 경우 CI/CD 구성을 선택한 다음 편집을 선택합니다.
3. 템플릿 적용 목록에서 Composer를 선택합니다.

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

게시할 때:

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

Composer 패키지 설치#

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

사전 조건:

• 패키지 레지스트리의 패키지.
• 패키지를 게시하는 프로젝트에서 패키지 레지스트리가 활성화되어 있습니다.
• 그룹 홈 페이지에 있는 그룹 ID.
• 다음 토큰 유형 중 하나:
  • 최소 api 범위로 설정된 개인 액세스 토큰.
  • read_package_registry, write_package_registry 또는 둘 다로 범위가 설정된 배포 토큰.
  • CI/CD 작업 토큰

패키지를 설치하려면:

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입니다.
   • <package_name>은 패키지의 composer.json 파일에 정의된 패키지 이름입니다.
   • <version>은 패키지 버전입니다.

2. GitLab 자격 증명으로 auth.json 파일을 생성합니다:

   개인 액세스 토큰 사용:

   composer config gitlab-token. <personal_access_token>
   

   auth.json 파일의 결과:

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

   배포 토큰 사용:

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

   auth.json 파일의 결과:

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

   CI/CD 작업 토큰 사용:

   composer config -- gitlab-token. gitlab-ci-token "${CI_JOB_TOKEN}"
   

   auth.json 파일의 결과:

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

   다음 명령으로 이를 해제할 수 있습니다:

   composer config --unset --auth gitlab-token.
   

   • 은 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>
   

소스에서 설치#

Git 저장소를 직접 가져와서 소스에서 설치할 수 있습니다. 이를 위해 다음 중 하나를 사용합니다:

• --prefer-source 옵션 사용:

  composer update --prefer-source
  

• composer.json에서 config 키 아래의 preferred-install 필드 사용:

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

SSH 액세스#

소스에서 설치할 때 composer는 프로젝트의 Git 저장소에 대한 액세스를 구성합니다. 프로젝트 가시성에 따라 액세스 유형이 다릅니다:

• 공개 프로젝트에서는 https Git URL이 사용됩니다. HTTPS로 저장소를 클론할 수 있는지 확인하세요.
• 내부 또는 비공개 프로젝트에서는 ssh Git URL이 사용됩니다. SSH로 저장소를 클론할 수 있는지 확인하세요.

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

배포 토큰으로 작업#

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

• 그룹 배포 토큰은 해당 그룹 또는 하위 그룹의 프로젝트에 게시된 모든 패키지에 액세스할 수 있습니다.
• 프로젝트 배포 토큰은 해당 특정 프로젝트에 게시된 패키지에만 액세스할 수 있습니다.

Composer 패키지 삭제#

사전 조건:

• Maintainer 또는 Owner 역할이 있어야 합니다.

패키지를 삭제하기 전에 관련 보안 위험을 이해하고 있는지 확인하세요.

패키지를 삭제하려면 다음 중 하나를 사용합니다:

• UI 사용.
• API 사용.

문제 해결#

캐싱#

성능을 향상시키기 위해 Composer는 패키지 관련 파일을 캐시합니다. Composer는 스스로 데이터를 제거하지 않습니다. 새 패키지가 설치될수록 캐시가 커집니다. 문제가 발생하면 다음 명령으로 캐시를 지웁니다:

composer clearcache

composer install 사용 시 인증 요구 사항#

패키지 아카이브 다운로드 엔드포인트에는 인증이 필요합니다. composer install을 사용할 때 자격 증명 프롬프트가 표시되면 auth.json 파일을 생성하는 Composer 패키지 설치 섹션의 지침을 따르세요.

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 의존성을 설치합니다.