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

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

GitLab 13.2에서 도입됨.
GitLab 13.3에서 GitLab Premium에서 GitLab Free로 변경됨.
Composer 2.0에서 GitLab 13.10에서 지원됨.
배포 토큰 지원이 GitLab 14.6에 추가됨.

GitLab의 Composer 패키지 레지스트리는 제한된 기능으로 인해 프로덕션 환경에 사용할 준비가 되지 않았습니다. 이 에픽에서 나머지 작업과 프로덕션 준비를 위한 일정이 상세히 설명되어 있습니다.

프로젝트의 패키지 레지스트리에 Composer 패키지를 게시하세요. 그런 다음 필요할 때마다 이러한 패키지를 종속성으로 사용할 수 있습니다.

특정 API 엔드포인트의 문서에 대한 자세한 내용은 Composer API documentation을 참조하세요.

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로 설정된 배포 토큰.

개인 액세스 토큰을 사용하여 패키지를 게시하려면:

패키지 API에 POST 요청을 보냅니다.
예를 들어 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>를 사용합니다.

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

패키지 API에 POST 요청을 보냅니다.
예를 들어 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 패키지를 패키지 레지스트리에 게시할 수 있습니다.

.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

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

게시한 패키지를 보려면 배포 > 패키지 레지스트리에 가서 Composer 탭을 선택합니다.

CI/CD 템플릿 사용

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

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

경고: 기존의 CI/CD 파일을 덮어쓰고 싶지 않은 경우에만 저장하지 마십시오.

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

게시할 때:

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

Composer 패키지 설치

패키지 아카이브 다운로드에 대한 권한은 GitLab 14.10에서 소개되었습니다.

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

전제 조건:

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

패키지를 설치하려면:

프로젝트의 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>은 패키지 버전입니다.

auth.json 파일을 GitLab 자격 증명과 함께 생성합니다:

개인 액세스 토큰을 사용하는 경우:

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로 설정된 토큰입니다.

만약 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에서는 기본적으로 auth.json에서 GitLab 토큰을 개인 토큰로 사용합니다. composer.json에 gitlab-domains 정의가 없는 경우, Composer는 GitLab 토큰을 기본 인증으로 사용하며, 이때 토큰은 사용자 이름과 빈 암호로 사용됩니다. 이로 인해 401 오류가 발생합니다.
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 name>": "source"
    }
  }
  ...
}

SSH 액세스

GitLab 16.4에 도입되었으며 composer_use_ssh_source_urls이라는 플래그로 제공됩니다. 기본 설정은 비활성화 상태입니다.
자체 호스팅하는 GitLab 16.5에서 활성화되었습니다.

플래그: 자체 호스팅하는 GitLab에서는 기본적으로 이 기능을 사용할 수 있습니다. 프로젝트 단위로 이 기능을 숨기려면 관리자가 composer_use_ssh_source_urls라는 기능 플래그를 비활성화할 수 있습니다. GitLab.com 및 전용 GitLab에서는 이 기능을 사용할 수 있습니다.

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

공개 프로젝트의 경우 https Git URL이 사용됩니다. HTTPS로 저장소 복제할 수 있는지 확인하세요.
내부 또는 비공개 프로젝트의 경우 ssh Git URL이 사용됩니다. SSH로 저장소 복제할 수 있는지 확인하세요.

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

배포 토큰 사용

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

그룹 배포 토큰은 해당 그룹이나 하위 그룹의 프로젝트에 발행된 모든 패키지에 액세스할 수 있습니다.
프로젝트 배포 토큰은 해당 프로젝트에 발행된 패키지에만 액세스할 수 있습니다.

문제 해결

캐싱

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

composer clearcache

`composer install` 사용 시 권한 요구

GitLab 14.9 이전에는 생성된 composer.lock이 이미 있으면 composer install을 사용하는 데 권한이 필요하지 않았습니다. composer.lock을 커밋했다면 자격 증명을 설정하지 않고도 CI에서 composer install을 수행할 수 있었습니다.

GitLab 14.10 이후에는 패키지 아카이브 다운로드 엔드포인트에서 권한이 필요합니다. composer install을 사용할 때 자격 증명 프롬프트가 표시되는 경우 컴포저 패키지 설치 섹션의 지침에 따라 auth.json 파일을 만드세요.

`composer.json` 파일을 찾을 수 없는 `Publish` 오류

The file composer.json was not found라는 오류가 표시될 수 있습니다.

이 문제는 패키지를 게시하는 데 필요한 구성 요구 사항을 충족하지 않을 때 발생합니다.

이 오류를 해결하려면 프로젝트 루트 디렉토리에 composer.json 파일을 커밋하세요.

지원되는 CLI 명령어

GitLab Composer 저장소에서는 다음과 같은 Composer CLI 명령어를 지원합니다.

composer install: Composer 종속성 설치
composer update: Composer 종속성의 최신 버전 설치

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

API를 사용하여 Composer 패키지를 게시

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

CI/CD 템플릿 사용

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

Composer 패키지 설치

소스로부터 설치

SSH 액세스

배포 토큰 사용

문제 해결

캐싱

`composer install` 사용 시 권한 요구

`composer.json` 파일을 찾을 수 없는 `Publish` 오류

지원되는 CLI 명령어

도움말

기능 사용 가능성과 제품 평가판

도움받기

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

API를 사용하여 Composer 패키지를 게시

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

CI/CD 템플릿 사용

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

Composer 패키지 설치

소스로부터 설치

SSH 액세스

배포 토큰 사용

문제 해결

캐싱

composer install 사용 시 권한 요구

composer.json 파일을 찾을 수 없는 Publish 오류

지원되는 CLI 명령어

도움말

기능 사용 가능성과 제품 평가판

도움받기

`composer install` 사용 시 권한 요구

`composer.json` 파일을 찾을 수 없는 `Publish` 오류