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

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
Status: Beta
caution
GitLab의 Composer 패키지 레지스트리는 개발 중이며 기능이 제한적이기 때문에
프로덕션 사용에 적합하지 않습니다. 이 에픽은
프로덕션 준비를 위해 남은 작업과 일정에 대한 세부 정보를 제공합니다.

프로젝트의 패키지 레지스트리에 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에 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>를 사용하세요.

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

  • 패키지 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. 파이프라인을 실행합니다.

게시된 패키지를 보려면 배포 > 패키지 레지스트리로 이동하여 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에서 preferred-install 필드를 사용하세요:

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

SSH 접근

  • GitLab 16.4에서 도입된 composer_use_ssh_source_urls라는 플래그가 있습니다. 기본적으로 비활성화되어 있습니다.
  • Self-managed GitLab 16.5에서 활성화되었습니다.
Self-managed GitLab에서는 기본적으로 이 기능이 사용 가능합니다. 프로젝트별로 기능을 숨기려면 관리자가 feature flag를 비활성화할 수 있습니다. GitLab.com 및 GitLab Dedicated에서는 이 기능을 사용할 수 있습니다.

소스에서 설치하면 composer가 프로젝트의 Git 저장소에 대한 접근을 구성합니다.

프로젝트 가시성에 따라 접근 유형은 다릅니다:

CI/CD 작업에서 GitLab CI/CD와 함께 SSH 키를 사용하여 ssh Git URL에 접근할 수 있습니다.

배포 토큰 작업하기

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

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

문제 해결

캐싱

성능을 개선하기 위해 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 의존성의 최신 버전을 설치합니다.