프로젝트의 패키지 레지스트리에 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 리포지터리에서 Packages 기능이 활성화되어 있어야 합니다.
• 프로젝트 개요 페이지에 표시되는 프로젝트 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>를 사용합니다.

게시된 패키지는 Deploy > Package registry로 이동해 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. 파이프라인을 실행합니다.

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

CI/CD 템플릿 사용#

더 자세한 Composer CI/CD 파일도 .gitlab-ci.yml 템플릿으로 제공됩니다.

1. 왼쪽 사이드바에서 Project overview를 선택합니다.
2. 파일 목록 위에서 Set up CI/CD를 선택합니다. 이 버튼이 없으면 CI/CD Configuration을 선택한 다음 Edit를 선택합니다.
3. Apply a template 목록에서 Composer를 선택합니다.

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

게시할 때 동작은 다음과 같습니다.

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

Composer 패키지 설치#

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

사전 요구 사항:

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

패키지를 설치하려면 다음 단계를 수행합니다.

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 job 토큰을 사용하는 경우:

   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 토큰을 사용자 이름으로, 빈 문자열을 비밀번호로 하는 basic-auth로 사용합니다. 이 경우 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로 리포지터리를 클론할 수 있는지 확인합니다.

CI/CD job에서는 GitLab CI/CD의 SSH 키를 사용해 ssh Git URL에 접근할 수 있습니다.

배포 토큰으로 작업#

Composer 패키지는 그룹 수준에서 접근하지만, 그룹 또는 프로젝트 배포 토큰으로도 접근할 수 있습니다.

• 그룹 배포 토큰은 해당 그룹이나 그 하위 그룹의 프로젝트에 게시된 모든 패키지에 접근할 수 있습니다.
• 프로젝트 배포 토큰은 해당 프로젝트에 게시된 패키지에만 접근할 수 있습니다.

Composer 패키지 삭제#

사전 요구 사항:

• Maintainer 또는 Owner 권한이 있어야 합니다.

패키지를 삭제하기 전에 관련 보안 위험을 먼저 이해해야 합니다.

패키지를 삭제하는 방법은 다음 두 가지입니다.

• UI 사용.
• API 사용.

문제 해결#

캐싱#

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

composer clearcache

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

패키지 아카이브 다운로드 엔드포인트에는 인증이 필요합니다. 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 의존성의 최신 버전을 설치합니다.