리포지토리에 매니페스트 제출

아티클
04/06/2023

애플리케이션을 설명하는 패키지 매니페스트가 만들어지면 이 매니페스트를 Windows 패키지 관리자 리포지토리에 제출할 수 있습니다. 이는 winget 도구에서 액세스할 수 있는 매니페스트 컬렉션이 포함된 공용 대상 리포지토리입니다. 매니페스트를 제출하려면 GitHub의 오픈 소스 https://github.com/microsoft/winget-pkgs 리포지토리에 업로드합니다.

새 매니페스트를 GitHub 리포지토리에 추가하기 위한 끌어오기 요청을 제출하면 자동화된 프로세스에서 매니페스트 파일의 유효성을 검사하고, 패키지가 Windows 패키지 관리자 정책을 준수하는지와 악성으로 알려진 패키지가 아닌지 확인합니다. 이 유효성 검사에 성공하면 패키지가 공용 Windows 패키지 관리자 리포지토리에 추가되어 winget 클라이언트 도구에서 검색할 수 있습니다. 오픈 소스 GitHub 리포지토리와 공용 Windows 패키지 관리자 리포지토리의 매니페스트에 대한 차이점을 확인합니다.

Important

Microsoft에는 어떤 이유로든 제출을 거부할 권리가 있습니다.

매니페스트 유효성 검사

매니페스트를 GitHub의 https://github.com/microsoft/winget-pkgs 리포지토리에 제출하면 매니페스트의 유효성이 자동으로 검사되고 Windows 에코시스템의 안전성이 평가됩니다. 매니페스트는 수동으로 검토할 수도 있습니다.

유효성 검사 절차에 대한 자세한 내용은 아래의 유효성 검사 절차 섹션을 참조하세요.

매니페스트를 제출하는 방법

매니페스트를 리포지토리에 제출하려면 다음 단계를 수행합니다.

1단계: 매니페스트 유효성 검사

winget 도구는 validate 명령을 제공하여 매니페스트를 올바르게 만들었는지 확인합니다. 매니페스트의 유효성을 검사하려면 이 명령을 사용합니다.

winget validate \<path-to-the-manifests>

유효성 검사에 실패하면 오류를 사용하여 줄 번호를 찾아서 수정합니다. 매니페스트의 유효성이 검사되면 리포지토리에 제출할 수 있습니다.

2단계: Windows 샌드박스로 매니페스트 테스트

Windows 패키지 관리자 리포지토리에는 매니페스트 제출을 테스트하기 위해 샌드박스에 Windows 패키지 관리자를 설치하는 스크립트가 포함되어 있습니다. PowerShell 스크립트를 실행하려면 Winget-pkgs 리포지토리로 이동합니다. PowerShell에서 다음 명령을 입력합니다.

powershell .\Tools\SandboxTest.ps1 manifests\m\Microsoft\VisualStudioCode\1.56.0

매니페스트 파일의 올바른 경로로 이 스크립트를 업데이트해야 할 수도 있습니다. .\Tools\SandboxTest.ps1 <path to manifest or manifest folder>

winget-pkgs 리포지토리의 전체 샌드박스 테스트 스크립트를 참조하세요.

3단계: 리포지토리 복제

Windows 패키지 관리자 커뮤니티 리포지토리의 포크를 만들고 해당 리포지토리를 로컬 컴퓨터에 복제하려면 다음을 수행합니다.

브라우저에서 https://github.com/microsoft/winget-pkgs로 이동하여 포크를 선택합니다.
Windows 명령 프롬프트 또는 PowerShell에서 다음 명령을 사용하여 포크를 복제합니다.
```
git clone <your-fork-name>
```
여러 제출을 입력하는 경우 포크 대신 분기를 만듭니다. 현재 제출당 하나의 매니페스트 파일만 허용합니다.
```
git checkout -b <branch-name>
```

4단계: 로컬 리포지토리에 매니페스트 추가

다음 폴더 구조의 리포지토리에 매니페스트 파일을 추가해야 합니다.

manifests / letter / publisher / application / version

manifests 폴더는 리포지토리의 모든 매니페스트에 대한 루트 폴더입니다.
letter 폴더는 게시자 이름의 소문자 첫 글자입니다. 예를 들어 게시자 Microsoft의 m입니다.
publisher 폴더는 소프트웨어를 게시하는 회사의 이름입니다. 예를 들어 Microsoft입니다.
application 폴더는 애플리케이션 또는 도구의 이름입니다. 예를 들어 VSCode입니다.
version 폴더는 애플리케이션 또는 도구의 버전입니다. 예를 들어 1.0.0입니다.

매니페스트의 PackageIdentifier 및 PackageVersion 값은 매니페스트 폴더 경로의 게시자, 애플리케이션 이름 및 버전과 일치해야 합니다. 자세한 내용은 패키지 매니페스트 만들기를 참조하세요.

5단계: 매니페스트를 원격 리포지토리에 제출

이제 새 매니페스트를 원격 리포지토리로 푸시할 준비가 되었습니다.

commit 명령을 사용하여 파일을 추가하고 변경 내용을 커밋하고 제출에 대한 정보를 제공합니다.
```
git commit -m "Submitting ContosoApp version 1.0.0" --all
```
push 명령을 사용하여 변경 내용을 원격 리포지토리로 푸시합니다.
```
git push
```

6단계: 끌어오기 요청 만들기

변경 내용이 푸시되면 https://github.com/microsoft/winget-pkgs로 돌아가서 포크 또는 분기를 기본 분기에 병합하는 끌어오기 요청을 만듭니다.

screenshot of pull request tab

제출 프로세스

끌어오기 요청이 만들어지면 매니페스트의 유효성을 확인하고 끌어오기 요청을 확인하는 자동화 프로세스가 시작됩니다. 이 프로세스 중에 설치 관리자 및 설치된 이진에 대한 테스트를 실행하여 제출의 유효성을 검사합니다.

진행 상황을 추적할 수 있도록 레이블이 끌어오기 요청에 추가됩니다. 레이블 및 프로세스에 대한 자세한 내용은 아래의 끌어오기 요청 레이블 섹션을 참조하세요.

완료되면 중재자가 제출을 수동으로 검토하고 승인되면 애플리케이션이 Windows 패키지 관리자 카탈로그에 추가됩니다.

프로세스 중에 오류가 발생하면 알림이 표시되고, 유용한 레이블 및 봇을 사용하여 제출을 수정할 수 있습니다. 일반적인 오류 목록은 아래 유효성 검사 프로세스 섹션을 참조하세요.

유효성 검사 프로세스

Windows 패키지 관리자 리포지토리에 매니페스트를 제출하기 위해 끌어오기 요청을 만들면 매니페스트의 유효성을 검사하고 끌어오기 요청을 처리하는 자동화 프로세스가 시작됩니다. GitHub 레이블을 사용하여 진행 상황을 공유하고 Microsoft와 통신할 수 있습니다.

제출에 대한 요구 사항

Windows 패키지 관리자 리포지토리에 대한 모든 애플리케이션 제출은 Windows 패키지 관리자 리포지토리 정책을 준수해야 합니다.

제출에 대한 기대치:

매니페스트는 스키마 요구 사항을 준수합니다.
매니페스트의 모든 URL은 안전한 웹 사이트로 연결됩니다.
설치 관리자 및 애플리케이션에는 바이러스가 없습니다. 의도치 않게 패키지가 맬웨어로 식별될 수 있습니다. 가양성이 아니라고 생각되면 설치 관리자를 Microsoft Defender 팀에 제출하여 분석할 수 있습니다.
애플리케이션은 관리자 및 비 관리자 모두에 대해 올바르게 설치 및 제거됩니다.
설치 관리자는 비 대화형 모드를 지원합니다.
모든 매니페스트 항목은 정확하고 잘못 해석되지 않습니다.
설치 관리자는 게시자의 웹 사이트에서 직접 제공됩니다.

정책의 전체 목록은 Windows 패키지 관리자 정책을 참조하세요.

끌어오기 요청 레이블

유효성 검사 중에 일련의 레이블이 끌어오기 요청에 적용되어 진행 상황을 전달합니다. 일부 레이블은 사용자에게 조치를 취하도록 안내하며, 다른 일부는 Windows 패키지 관리자 엔지니어링 팀으로 보내집니다.

상태 레이블

다음 표에서는 발생할 수 있는 상태 레이블에 대해 설명합니다.

레이블	자세히
Azure-Pipeline-Passed	매니페스트가 테스트 통과를 완료했습니다. 승인을 기다리는 중입니다. 테스트를 통과하는 동안 문제가 발생하지 않으면 자동으로 승인됩니다. 테스트가 실패하면 수동 검토를 위해 플래그가 지정될 수 있습니다.
차단 문제	이 레이블은 차단 문제가 있으므로 끌어오기 요청을 승인할 수 없음을 나타냅니다. 포함된 오류 레이블을 통해 차단 문제가 무엇인지 파악할 수 있습니다.
Needs-Attention	이 레이블은 Windows 패키지 관리자 개발 팀에서 끌어오기 요청을 조사해야 함을 나타냅니다. 이는 수동 검토를 필요로 하는 테스트 오류 또는 커뮤니티에서 끌어오기 요청에 추가한 주석으로 인한 것입니다.
Needs-Author-Feedback	제출에 실패했음을 나타냅니다. 사용자에게 끌어오기 요청을 다시 할당합니다. 10일 이내에 문제가 해결되지 않으면 봇에서 끌어오기 요청을 닫습니다. Needs-Author-Feedback 레이블은 일반적으로 업데이트해야 하는 끌어오기 요청에 오류가 있거나 끌어오기 요청을 검토하는 사용자에게 질문이 있는 경우에 추가됩니다.
유효성 검사 완료됨	테스트 통과가 성공적으로 완료되었으며 끌어오기 요청이 병합됨을 나타냅니다.

오류 레이블

다음 표에서는 발생할 수 있는 오류 레이블에 대해 설명합니다. 모든 오류 사례가 사용자에게 즉시 할당되는 것은 아닙니다. 일부 경우에는 수동 유효성 검사를 트리거할 수 있습니다.

레이블	자세히
Binary-Validation-Error	이 끌어오기 요청에 포함된 애플리케이션이 설치 관리자 검사 테스트를 통과하지 못했습니다. 이 테스트는 애플리케이션이 경고 없이 모든 환경에 설치되도록 설계되었습니다. 이 오류에 대한 자세한 내용은 아래의 이진 파일 유효성 검사 오류 섹션을 참조하세요.
Error-Analysis-Timeout	Binary-Validation-Test 테스트 시간이 초과되었습니다. 끌어오기 요청이 조사를 위해 Windows 패키지 관리자 엔지니어에게 할당됩니다.
Error-Hash-Mismatch	InstallerURL에 제공된 InstallerSha256 해시가 일치하지 않기 때문에 제출된 매니페스트를 처리할 수 없습니다. 끌어오기 요청에서 InstallerSha256을 업데이트하고 다시 시도하세요.
Error-Installer-Availability	유효성 검사 서비스에서 설치 관리자를 다운로드할 수 없습니다. 차단되는 Azure IP 범위와 관련되어 있거나 설치 관리자 URL이 잘못되었을 수 있습니다. InstallerURL이 올바른지 확인하고 다시 시도하세요. 이로 인해 오류가 발생했을 때 주석을 추가하면 조사를 위해 끌어오기 요청이 Windows 패키지 관리자 엔지니어에게 할당됩니다.
Manifest-Installer-Validation-Error	MSIX 패키지를 평가하는 동안 매니페스트에 불일치 또는 값이 없습니다.
Manifest-Path-Error	매니페스트 파일은 특정 폴더 구조에 배치해야 합니다. 이 레이블은 제출물의 경로에 문제가 있음을 나타냅니다. 예를 들어 폴더 구조에 필요한 형식이 없습니다. 매니페스트와 경로를 업데이트하여 끌어오기 요청을 다시 제출합니다.
Manifest-Validation-Error	제출된 매니페스트에 구문 오류가 있습니다. 매니페스트의 구문 문제를 해결하고 다시 제출합니다. 매니페스트 형식 및 스키마에 대한 자세한 내용은 필수 형식을 참조하세요.
PullRequest-Error	제출된 모든 파일이 매니페스트 폴더에 없거나 끌어오기 요청에 둘 이상의 패키지 또는 버전이 있어 끌어오기 요청이 잘못되었습니다. 끌어오기 요청을 업데이트하여 문제를 해결하고 다시 시도하세요.
URL-Validation-Error	URL 유효성 검사 테스트에서 URL을 찾을 수 없으며 HTTP 오류 상태 코드(403 또는 404)로 응답하거나 URL 평판 테스트가 실패했습니다. 끌어오기 요청 확인 세부 정보를 확인하여 의심스러운 URL을 확인할 수 있습니다. 이 문제를 해결하려면 의심스러운 URL을 업데이트하여 HTTP 오류 상태 코드를 확인합니다. HTTP 오류 상태 코드로 인한 문제가 아닐 경우 검토를 위해 URL을 제출하여 평판 오류를 방지할 수 있습니다.
Validation-Defender-Error	동적 테스트 중에 Microsoft Defender에서 문제를 보고했습니다. 이 문제를 재현하려면 애플리케이션을 설치한 다음, Microsoft Defender 전체 검색을 실행합니다. 문제를 재현할 수 있는 경우 이진을 수정하거나 가양성 지원에 대한 분석을 위해 제출합니다. 문제를 재현할 수 없는 경우 주석을 추가하여 Windows 패키지 관리자 엔지니어가 조사하도록 합니다.
Validation-Domain	InstallerURL이 예상되는 도메인과 일치하지 않는 경우 테스트에서 도메인을 확인했습니다. Windows 패키지 관리자 정책에서는 InstallerUrl이 ISV의 릴리스 위치에서 직접 제공되어야 합니다. 이것이 거짓 검색이라고 생각되는 경우 끌어오기 요청에 주석을 추가하여 Windows 패키지 관리자 엔지니어가 조사하도록 합니다.
Validation-Error	수동 승인 중에 Windows 패키지 관리자 유효성 검사에 실패했습니다. 다음 단계는 해당 주석을 확인합니다.
Validation-Executable-Error	설치 테스트 중에 테스트에서 기본 애플리케이션을 찾을 수 없습니다. 모든 플랫폼에 애플리케이션이 제대로 설치되어 있는지 확인합니다. 애플리케이션에서 애플리케이션을 설치하지 않고 리포지토리에 계속 포함해야 하는 경우 끌어오기 요청에 주석을 추가하여 Windows 패키지 관리자 엔지니어가 조사하도록 합니다.
Validation-Hash-Verification-Failed	InstallerSha256이 InstallerURL 해시와 더 이상 일치하지 않으므로 설치 테스트 중에 애플리케이션을 설치하지 못했습니다. 애플리케이션이 베니티 URL 뒤에 있고 InstallerSha256을 업데이트하지 않고 설치 관리자가 업데이트된 경우 이 문제가 발생할 수 있습니다. 이 문제를 해결하려면 InstallerURL과 연결된 InstallerSha256을 업데이트하고 다시 제출합니다.
Validation-HTTP-Error	설치 관리자에 사용되는 URL이 HTTPS 프로토콜을 사용하지 않습니다. HTTPS를 사용하도록 InstallerURL을 업데이트하고 끌어오기 요청을 다시 제출합니다.
Validation-Indirect-URL	URL이 ISV 서버에서 직접 오지 않습니다. 테스트 결과 리디렉터 사용이 확인되었습니다. Windows 패키지 관리자 정책에서는 InstallerUrl이 ISV의 릴리스 위치에서 직접 제공되어야 하므로 이는 허용되지 않습니다. 리디렉션을 제거하고 다시 제출합니다.
Validation-Installation-Error	이 패키지의 수동 유효성 검사 중에 일반적인 오류가 발생했습니다. 다음 단계는 해당 주석을 확인합니다.
Validation-Merge-Conflict	병합 충돌로 인해 이 패키지의 유효성을 검사할 수 없습니다. 병합 충돌을 해결하고 끌어오기 요청을 다시 제출합니다.
Validation-MSIX-Dependency	MSIX 패키지에 확인할 수 없는 패키지에 대한 종속성이 있습니다. 누락된 구성 요소를 포함하도록 패키지를 업데이트하거나 매니페스트 파일에 종속성을 추가하고 끌어오기 요청을 다시 제출합니다.
Validation-Unapproved-URL	InstallerURL이 예상되는 도메인과 일치하지 않는 경우 테스트에서 도메인을 확인했습니다. Windows 패키지 관리자 정책에서는 InstallerUrl이 ISV의 릴리스 위치에서 직접 제공되어야 합니다.
Validation-Unattended-Failed	설치하는 동안 테스트 시간이 초과되었습니다. 이는 애플리케이션이 자동으로 설치되지 않기 때문일 수 있습니다. 다른 오류가 발생하여 테스트를 중지했기 때문일 수도 있습니다. 사용자 입력 없이 매니페스트를 설치할 수 있는지 확인합니다. 도움이 필요한 경우 끌어오기 요청에 주석을 추가하면 Windows 패키지 관리자 엔지니어가 조사합니다.
Validation-Uninstall-Error	제거 테스트 중에 애플리케이션이 제거 후 완전히 정리되지 않았습니다. 자세한 내용은 해당 주석을 확인합니다.
Validation-VCRuntime-Dependency	패키지에 확인할 수 없는 C++ 런타임에 대한 종속성이 있습니다. 누락된 구성 요소를 포함하도록 패키지를 업데이트하거나 매니페스트 파일에 종속성을 추가하고 끌어오기 요청을 다시 제출합니다.

콘텐츠 정책 레이블

다음 표에는 콘텐츠 정책 레이블이 나열되어 있습니다. 이러한 레이블 중 하나가 추가되면 매니페스트 메타데이터에서 추가 수동 콘텐츠 검토를 트리거하여 메타데이터가 Windows 패키지 관리자 정책을 따르는지 확인합니다.

레이블	자세히
Policy-Test-2.1	일반 콘텐츠 요구 사항을 참조하세요.
Policy-Test-2.2	이름, 로고, 원본 및 제3자를 포함하는 콘텐츠를 참조하세요.
Policy-Test-2.3	유해성을 참조하세요.
Policy-Test-2.4	명예훼손, 중상, 비방 및 위협을 참조하세요.
Policy-Test-2.5	악의적 콘텐츠를 참조하세요.
Policy-Test-2.6	음주, 흡연, 무기 및 마약을 참조하세요.
Policy-Test-2.7	성인 콘텐츠를 참조하세요.
Policy-Test-2.8	불법 활동을 참조하세요.
Policy-Test-2.9	과도한 신성 모독 및 부적절한 콘텐츠를 참조하세요.
Policy-Test-2.10	국가/지역 관련 요구 사항을 참조하세요.
Policy-Test-2.11	연령별 등급을 참조하세요.
Policy-Test-2.12	사용자 생성 콘텐츠를 참조하세요.

내부 레이블

다음 표에는 내부 오류 레이블이 나열되어 있습니다. 내부 오류가 발생하면 조사를 위해 Windows 패키지 관리자 엔지니어에게 끌어오기 요청이 할당됩니다.

레이블	자세히
Internal-Error-Domain	URL의 도메인 유효성 검사 중에 오류가 발생했습니다.
Internal-Error-Dynamic-Scan	설치된 이진의 유효성을 검사하는 동안 오류가 발생했습니다.
Internal-Error-Keyword-Policy	매니페스트의 유효성 검사 중에 오류가 발생했습니다.
Internal-Error-Manifest	매니페스트의 유효성 검사 중에 오류가 발생했습니다.
Internal-Error-NoArchitectures	애플리케이션인 경우 테스트에서 아키텍처를 확인할 수 없어 오류가 발생했습니다.
Internal-Error-NoSupportedArchitectures	현재 아키텍처가 지원되지 않기 때문에 오류가 발생했습니다.
Internal-Error-PR	끌어오기 요청을 처리하는 중 오류가 발생했습니다.
Internal-Error-Static-Scan	설치 관리자를 정적으로 분석하는 동안 오류가 발생했습니다.
Internal-Error-URL	설치 관리자의 평판 유효성 검사 도중에 오류가 발생했습니다.
Internal-Error	테스트 통과 중에 일반 오류 또는 알 수 없는 오류가 발생했습니다.

이진 유효성 검사 오류

Pull Request의 유효성 검사가 Installers Scan 테스트에 실패하고 Binary-Validation-Error 레이블이 표시되면 애플리케이션이 모든 환경에서 설치에 실패했음을 의미합니다.

설치 관리자 검사 테스트

뛰어난 애플리케이션 설치 사용자 환경을 제공하려면 Windows 패키지 관리자는 환경에 관계없이 모든 애플리케이션이 오류 없이 PC에 설치되도록 해야 합니다. 한 가지 주요 테스트는 널리 사용되는 다양한 바이러스 백신 구성에 대한 경고 없이 모든 애플리케이션이 설치되도록 하는 것입니다. Windows는 기본 제공 Microsoft Defender 바이러스 백신 프로그램을 제공하지만 많은 엔터프라이즈 고객과 사용자가 다른 바이러스 백신 소프트웨어를 사용합니다.

Windows 패키지 관리자 리포지토리에 대한 각 제출은 여러 바이러스 백신 프로그램을 통해 실행됩니다. 이러한 프로그램에는 PUA(잠재적으로 원치 않는 애플리케이션) 및 맬웨어를 식별하는 다양한 바이러스 검색 알고리즘이 있습니다.

이진 유효성 검사 오류 해결

애플리케이션의 유효성 검사에 실패하는 경우 Microsoft는 먼저 바이러스 백신 공급 업체와 함께 플래그가 지정된 소프트웨어가 가양성인지 확인하려고 합니다. 대부분의 경우 알림 및 유효성 검사 후에 바이러스 백신 공급 업체에서 해당 알고리즘을 업데이트하고 애플리케이션이 전달됩니다.

경우에 따라 바이러스 백신 공급업체는 검색된 코드 변칙이 가양성인지 여부를 확인할 수 없습니다. 이 경우 애플리케이션을 Windows 패키지 관리자 리포지토리에 추가할 수 없습니다. 끌어오기 요청은 Binary-Validation-Error 레이블로 거부됩니다.

Binary-Validation-Error 레이블이 끌어오기 요청에 표시되는 경우 소프트웨어를 업데이트하여 PUA로 검색된 코드를 제거합니다.

경우에 따라 디버깅 및 하위 수준 작업에 사용되는 정품 도구는 바이러스 백신 공급 업체에 PUA로 표시됩니다. 이는 필요한 디버깅 코드가 원하지 않는 소프트웨어와 유사한 서명을 가지기 있기 때문입니다. 이 코딩 방법은 합법적이지만 Windows 패키지 관리자 리포지토리는 불행히도 이러한 애플리케이션을 허용할 수 없습니다.

제출 문제 해결

Windows 패키지 관리자 제출이 실패하면 위에서 설명한 레이블을 사용하여 실패 이유를 조사할 수 있습니다.

끌어오기 요청 실패를 조사하려면 다음 단계를 수행합니다.

일부 검사에 실패했습니다.라는 문자열이 있는 웹 페이지의 맨 아래에 끌어오기 요청 실패가 나타납니다. 실패한 유효성 검사 옆에 있는 세부 정보 링크를 선택하여 Azure Pipelines 페이지로 이동합니다.
Azure Pipelines 페이지에서 0 오류/0 경고 링크를 선택합니다.
다음 페이지에서 실패한 작업을 선택합니다.
다음 페이지에는 실패한 작업에 대한 출력이 표시됩니다. 출력을 통해 매니페스트를 수정하는 데 필요한 변경 사항을 식별할 수 있습니다.

다음 예제에서는 설치 유효성 검사 작업 중 오류가 발생했습니다.