failproofai publish는 앞에 지정된 정책 파일들로부터 이 세 파일을 모두 작성하고, 릴리스를 생성한 후 업로드합니다.
1. 정책 작성하기
빈 템플릿 대신, 이미 동작하는 예시에서 시작하세요:<name>.mjs를 작성하고 종료합니다 — 네트워크 접근도, git 작업도, 배포도 없습니다. 작성되는 파일에는 git push --force를 차단하는 정책 하나가 포함되어 있습니다. 이미 파일이 존재하면 덮어쓰지 않습니다.
정책은 커스텀 정책과 동일한 API를 사용합니다. 팩에서 중요한 추가 필드가 두 가지 있습니다:
defaultEnabled를 생략하면 기본값은 false입니다. 단순히 failproofai policies add를 실행하면 표시된 정책만 활성화됩니다 — 모르는 사람의 모든 정책을 자동으로 설치할지 여부는 설치 도구가 사용자 대신 결정해서는 안 될 사항입니다.
파일은 원하는 만큼 작성할 수 있습니다. 카테고리당 하나씩 작성하면 가독성이 좋습니다. 정책을 등록하는 디렉터리의 모든 파일은 팩이 가져야 할 단일 아티팩트로 번들링됩니다.
2. 먼저 로컬에서 테스트하기
다른 사람이 볼 수 있기 전에, 이 머신에서 파일을 직접 적용해 보세요:3. 배포하기
- 파일명이 아닌 내용으로 정책 파일을 찾습니다 —
failproofai를 임포트하고customPolicies.add를 호출하는 파일을 찾으므로,guards.mjs는 찾아내고 관련 없는policies.mjs는 무시합니다. 하위 디렉터리는 탐색하지 않으므로, 테스트 픽스처가 실수로 포함되지 않습니다. - 파일이 있는 디렉터리에서
git remote get-url origin으로 저장소를 읽고 버전을 결정합니다. - 자격증명을 찾습니다:
GITHUB_TOKEN,GH_TOKEN, 또는gh auth login. 릴리스 쓰기 권한만 필요하며, 절대 출력되지 않습니다. - 저장소가 없으면 생성합니다. 빌드 전에 이루어지므로, 다음 단계에서 거부된 팩이 릴리스 없는 빈 저장소를 남길 수 있습니다.
- 세 개의 에셋을 빌드하고 로더 자체의 규칙으로 유효성을 검사합니다 — 타인의 머신에 설치될 수 있는지 판단하는 동일한 코드를 사용하므로, 설치될 수 없는 팩은 여기서 실패합니다. 아직 수정할 수 있습니다.
- 릴리스를 생성하거나 재사용하고 업로드하며, 같은 이름의 에셋을 교체합니다.
에셋 이름은 고정되어 있습니다 — 소비자의 CLI가 API 호출이나 디스커버리 없이 URL을 직접 구성할 때 사용하는 이름이기 때문입니다.
빌드 시 거부되는 경우:
publisher/name 형식이 아닌 id, /를 포함하는 정책 이름, alwaysOn을 선언하는 정책, description/category/match 누락, 아무것도 등록하지 않는 엔트리, 로컬 파일을 임포트하는 엔트리.
자동으로 결정된 값을 재정의하려면:
--id는 저장소와 다른 경우 팩 id를 설정하고, --tag는 릴리스 태그를 설정하며, --notes는 자동 생성된 릴리스 노트를 대체합니다 — policies show --releases가 각 릴리스의 정책 수와 커밋 정보를 읽는 곳이기도 합니다 — --out은 에셋이 저장될 위치를 지정하고(기본값: dist-pack), --dry-run은 자격증명 없이 빌드만 하고 배포하지 않습니다.
이제 누구든 failproofai policies add acme/support-agent로 설치할 수 있습니다. 버전 고정 및 일부만 선택하는 방법은 정책 팩을 참고하세요.
정책 허브에 등재하기
GitHub 저장소에failproofai-policies 토픽을 추가하세요. 제출 양식도 없고 승인 대기열도 없습니다: 정책 허브의 크롤러가 다음 순회 시 저장소를 자동으로 발견합니다. 토픽은 검토 대상으로 올리는 것에 불과하며, 실제로 등재되려면 매니페스트가 자체 SHA256SUMS로 검증되고 CLI가 사용하는 동일한 규칙으로 파싱되는 릴리스가 있어야 합니다 — 이것이 바로 failproofai publish가 생성하는 것입니다.
버전 결정 방식
버전은 배포 중인 커밋 — 12자리 짧은 sha:a1b2c3d4e5f6 입니다. 선택할 것도, 증가시킬 것도 없으며, 버전 이름이 정확히 해당 바이트의 출처를 나타내므로 동일한 소스를 두 번 배포하면 동일한 버전이 됩니다.
현재 작업 트리에서 읽으며, 저장소의 릴리스 기록에서 읽지 않으므로, 새로 클론한 머신이나 에어갭 머신도 GitHub에 문의하지 않고 동일한 답을 계산합니다.
버전이 커밋을 가리키므로 해당 커밋이 존재해야 합니다. 터미널에서 publish를 실행하면 자동으로 처리해 줍니다: 저장소가 없으면 초기화하고, 변경된 정책 파일을 빌드 전에 커밋합니다. 다음 상황에서는 거부하며 — --version을 해결책으로 안내합니다 — 터미널 없이 실행할 때(CI 러너에서 만든 커밋은 다른 곳에 존재하지 않음), 정책 파일 외의 파일이 커밋되지 않았을 때, 또는 아직 커밋이 없는 체크아웃에서. HEAD에 태그가 있으면 sha보다 우선합니다 — v1.2.0으로 태그한 사람은 이 릴리스가 무엇인지 이미 명시한 것입니다.
sha 자체에는 순서 정보가 없으므로, failproofai policies show <owner>/<repo> --releases로 어떤 릴리스가 먼저 나왔는지 확인하세요 — 최신 순으로 표시됩니다.
새 버전 배포하기
변경 사항을 커밋하고failproofai publish를 다시 실행하세요 — 새 커밋이 새 버전이 됩니다. 소비자는 동일하게 failproofai policies add를 실행합니다. 터미널 없이, 또는 선택 플래그와 함께 실행하면 이전에 선택한 하위 집합을 유지하며, 꺼둔 정책은 꺼진 상태로 유지됩니다. 터미널에서 플래그 없이 실행하면 기본값이 미리 체크된 선택기가 열리고, 사용자의 답변이 기존 선택을 대체합니다.
정책의 이름을 변경하는 것은 호환성을 깨는 변경입니다: 꺼둔 정책 이름이 더 이상 존재하지 않게 되고, 새 이름은 defaultEnabled 설정대로 동작합니다.
사용자가 신뢰하는 것
SHA256SUMS는 아티팩트와 같은 릴리스에 있으므로, 배포한 바이트가 맞다는 것을 증명합니다 — 누가 배포했는지가 아닙니다. 저장소에 쓰기 권한이 있는 사람은 두 파일 모두 수정할 수 있습니다. 사용자의 보호 장치는 설치 시 다이제스트가 고정되어, 이후 배포한 내용이 변경될 수 없다는 것입니다.
쓰기 권한을 직접 통제하는 저장소에서 배포하고, 팩 릴리스를 패키지 배포처럼 취급하세요.
저장소는 반드시 공개여야 합니다. 설치는 자격증명 없는 익명 HTTPS로 이루어지므로, 기존 비공개 저장소는 빌드나 업로드 전에 거부되며, publish가 생성하는 저장소도 같은 이유로 공개입니다. --allow-private는 세 에셋을 다른 방식으로 전달하는 경우를 위한 재정의 옵션이며, policies add로는 접근할 수 없음을 명시합니다. 릴리스만 중요합니다: 설치는 releases/download/<tag>/<asset>에서 읽으며 git 트리는 절대 접근하지 않습니다.
적용 전 관찰 모드 사용하기
매니페스트에"effect": "observe"를 선언할 수 있으며 — failproofai publish --effect observe로 설정합니다. 이 정책들은 실행되지만 판정은 기록만 되고 폐기됩니다 — 아무것도 차단되지 않습니다. 실제 트래픽에 대해 새 규칙을 측정한 후 실제 작업을 방해하기 전에 적용하는 방법입니다.