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

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated Status: Beta

경고: 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을 사용할 수 있습니다: 

    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>를 사용합니다.

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

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

    예시로 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를 선택합니다.

경고: 기존 CI/CD 파일을 덮어써야 하는 경우를 제외하고는 저장하지 마세요.

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

게시할 때:

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

Composer 패키지 설치

패키지 레지스트리에서 패키지를 설치하여 해당 패키지를 종속성으로 사용할 수 있습니다.

필수 사항:

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

패키지를 설치하려면:

  1. 프로젝트의 composer.json 파일에 패키지 레지스트리 URL을 추가하고, 설치할 패키지 이름과 버전을 함께 지정하세요:

    • 그룹의 패키지 레지스트리에 연결: 

      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.<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입니다.
    • <personal_access_token>은 api로 설정된 경우, 또는 <deploy_token>은 read_package_registry 및/또는 write_package_registry로 설정된 경우입니다.

  3. GitLab 자체 관리 형식 인스턴스인 경우, 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

    참고: 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>

경고: 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 이름>": "source"
    }
  }
  ...
 }

SSH 액세스

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

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

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

배포 토큰 사용하기

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

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

문제 해결

캐싱

성능을 개선하기 위해 Composer는 패키지와 관련된 파일을 캐시합니다. Composer는 자체적으로 데이터를 제거하지 않습니다. 새 패키지가 설치될수록 캐시가 증가합니다. 문제가 발생하면 다음 명령을 사용하여 캐시를 지우세요. 

composer clearcache

composer install 사용 시 인증 요구사항

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 종속성의 최신 버전 설치.