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

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated Status: Beta
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는 프로젝트 개요 페이지에 표시됩니다.
  • 다음 중 하나의 토큰 유형:

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

  • 패키지 APIPOST 요청을 보냅니다.

    예시로, curl을 사용할 수 있습니다:

    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>를 사용하세요.

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

  • 패키지 APIPOST 요청을 보냅니다.

    예시로, curl을 사용할 수 있습니다:

    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>를 사용하세요.

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

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

게시된 패키지를 보려면 배포 > 패키지 레지스트리로 이동한 다음 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. 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입니다.
    • api로 설정된 개인 액세스 토큰 또는 read_package_registry 및/또는 write_package_registry로 설정된 배포 토큰을 사용합니다.
  3. GitLab Self-Managed형 인스턴스인 경우, composer.jsongitlab-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.jsongitlab-domains가 정의되어 있지 않으면, Composer는 GitLab 토큰을 기본 인증으로 사용하며, 토큰을 사용자 이름으로 하고 빈 암호로 사용합니다. 이로 인해 401 오류가 발생합니다.
  4. composer.jsonauth.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의 경우, 이 기능을 사용할 수 있습니다.

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

GitLab CI/CD에서 SSH 키를 사용하여 CI/CD 작업에서 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 의존성의 최신 버전을 설치합니다.