패키지 레지스트리의 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는 프로젝트 개요 페이지에 표시됩니다.
다음 중 하나의 토큰 유형:
- 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 템플릿 사용

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

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

기존의 CI/CD 파일을 덮어쓰기 하려면 저장하지 마십시오.

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

게시할 때:

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

Composer 패키지 설치

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

사전 요구 사항:

패키지 레지스트리에 패키지가 있어야 합니다.
패키지를 게시하는 프로젝트에서 패키지 레지스트리가 활성화되어 있어야 합니다.
그룹의 홈 페이지에 있는 그룹 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>은 패키지 버전입니다.

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로 설정된 배포 토큰을 사용합니다.

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
```
GitLab.com에서 Composer는 기본적으로 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라는 플래그로 제공됩니다.
Self-Managed에서 활성화되었습니다. GitLab 16.5에서.

플래그: Self-Managed 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` 사용 시 권한 요구

패키지 아카이브 다운로드 엔드포인트를 사용할 때 권한이 필요합니다. 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 의존성의 최신 버전을 설치합니다.

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

API를 사용하여 Composer 패키지를 게시합니다.

CI/CD를 사용하여 Composer 패키지를 게시합니다.

CI/CD 템플릿 사용

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

Composer 패키지 설치

소스로부터 설치

SSH 액세스

배포 토큰 사용

문제 해결

캐싱

`composer install` 사용 시 권한 요구

`The file composer.json was not found`로 발행이 실패하는 경우

지원되는 CLI 명령어

도움말

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

도움받기

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

API를 사용하여 Composer 패키지를 게시합니다.

CI/CD를 사용하여 Composer 패키지를 게시합니다.

CI/CD 템플릿 사용

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

Composer 패키지 설치

소스로부터 설치

SSH 액세스

배포 토큰 사용

문제 해결

캐싱

composer install 사용 시 권한 요구

The file composer.json was not found로 발행이 실패하는 경우

지원되는 CLI 명령어

도움말

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

도움받기

`composer install` 사용 시 권한 요구

`The file composer.json was not found`로 발행이 실패하는 경우