GitHub Dependabot의 Agent Package Manager(APM) 지원 해부: apm.yml 핀 방식과 apm.lock.yaml 재생성 경계

apm.yml의 태그·40자 SHA·브랜치 핀 방식에 따라 Dependabot 버전 업데이트 게이트가 매니페스트와 apm.lock.yaml을 갱신하고 CI 검증으로 이어지는 흐름을 표현한 개념 일러스트다. 실제 도구 화면이 아니다.

2026년 11월 3일 GitHub가 AI 에이전트용 스킬(Skills), 프롬프트, 지침(Instructions) 의존성을 관리하는 Agent Package Manager(APM)에 대해 Dependabot 버전 업데이트(Version Updates)를 정식 출시(GA)했다. 저장소의 .github/dependabot.yml에 package-ecosystem: "apm"을 추가하면, Dependabot이 apm.yml에 선언된 Git 의존성의 새 버전을 감지해 Pull Request를 열고 기존 apm.lock.yaml이 존재할 경우 이를 함께 재생성한다. GitHub Changelog 공식 발표

결론부터 말하면, 이번 지원은 ‘버전 업데이트(Version updates)’만 다루며 취약점을 감지하는 ‘보안 업데이트(Security updates)’가 아니다. 또한 저장소에 apm.lock.yaml이 커밋되어 있지 않으면 Dependabot이 락파일을 새로 만들어주지 않는다. 특히 브랜치(#main) 기준으로 스킬을 참조하는 프로젝트가 apm.lock.yaml을 커밋하지 않은 상태라면 Dependabot이 매니페스트도, 락파일도 바꾸지 못해 사실상 업데이트가 동작하지 않으며, 7자리 축약 커밋 SHA나 로컬 경로, MCP 서버 설정 항목은 업데이트 대상에서 제외된다는 점을 먼저 구분해야 한다.

이 글은 GitHub Changelog 발표문과 GitHub Docs의 지원 생태계 문서, Dependabot Core APM 구현 사양(#14350)을 바탕으로 핀(Pin) 방식별 업데이트 동작과 apm.lock.yaml 관리 규칙을 정리한 가이드다. 실제 GitHub Enterprise Server 3.24 환경에서의 실행은 포함하지 않으며, 로컬 Python 코드는 apm.yml 의존성 표기 형식별 Dependabot 처리 판정 로직만 검증한다.

1. 버전 업데이트와 보안 업데이트, 매니페스트와 락파일의 경계

에이전트 스킬과 프롬프트는 일반 라이브러리와 달리 자연어 지침 자체가 에이전트의 도구 호출과 파일 수정 행동을 바꾼다. 따라서 Dependabot이 자동으로 PR을 열어준다는 사실과 그 변경이 안전하다는 사실은 엄격히 분리해야 한다.

구분 항목	Dependabot APM 지원 범위 (포함)	지원하지 않거나 별도 검증이 필요한 범위 (제외)
업데이트 유형	버전 업데이트(Version updates) 전용. `.github/dependabot.yml`의 주기에 따라 상위 Git 저장소의 새 릴리스 태그·커밋을 확인해 PR 생성	보안 업데이트(Security updates) 및 Dependabot Alerts 미지원. 악성 프롬프트 주입(Prompt Injection)이나 위험한 스킬 변경을 자동 탐지하지 않음
대상 매니페스트 섹션	`apm.yml` 내 `dependencies.apm` 및 `devDependencies.apm`에 선언된 지원 형식의 Git 의존성 (`ignore`, `groups`, `cooldown` 옵션 지원)	고정되지 않은(Unpinned) 항목, 40자 미만의 축약 커밋 SHA, 로컬 파일 경로(`./`, `../`), `apm.yml` 내 MCP 서버 설정 항목
락파일(`apm.lock.yaml`) 처리	저장소에 이미 `apm.lock.yaml`이 존재할 때만 `apm lock`을 실행해 해결된 커밋과 콘텐츠 해시를 재생성함	`apm.lock.yaml`이 없는 저장소에서 새 락파일을 생성하지 않음. 재현 가능한 설치(`apm install --frozen`)를 원한다면 반드시 락파일을 먼저 생성해 커밋해야 함
지원 플랫폼 및 버전을 타는 범위	GitHub.com의 모든 플랜에서 즉시 사용 가능 (Generally Available)	자체 호스팅 환경은 GitHub Enterprise Server(GHES) 3.24부터 지원 예정이므로 구버전 GHES에서는 동작하지 않음

2. `apm.yml` 의존성 핀(Pin) 방식에 따른 Dependabot 동작 차이

Dependabot은 apm.yml에 적힌 Git 의존성의 참조(Ref) 형태에 따라 매니페스트를 수정할지, 락파일만 수정할지, 아니면 아예 건너뛸지를 다르게 결정한다.

핀(Pin) 지정 방식	`apm.yml` 표기 예시	`apm.yml` 변경 여부	`apm.lock.yaml` 변경 여부 (존재 시)	실무 주의사항
1. 릴리스 태그 핀 (Tag Pin / 가상 패키지 / 패키지 스코프 태그)	`owner/repo#v1.2.0` `owner/repo/skills/review#v1.2.0` `owner/repo#review--v1.2.0`	변경됨 (최신 릴리스 태그로 업데이트)	재생성됨 (새 태그의 커밋 및 해시 반영)	가장 명확하게 PR diff에서 버전 변화를 확인할 수 있는 권장 방식
2. 전체 40자 커밋 SHA 핀 (Full 40-char SHA)	`owner/repo#a1b2c3d4e5f60718293a4b5c6d7e8f9012345678`	변경됨 (최신 어노테이션 릴리스 태그의 40자 커밋 SHA로 이동하며 `# vX.Y.Z` 주석 부착)	재생성됨	불변 커밋 고정이 필요할 때 적합함. `apm update`의 동작과 일치함
3. 브랜치 핀 (Branch Pin)	`owner/repo#main`	변경되지 않음 (`#main` 그대로 유지)	재생성됨 (해당 브랜치의 최신 커밋으로 락파일만 이동)	저장소에 `apm.lock.yaml`이 없으면 매니페스트도 바뀌지 않아 업데이트 PR이 생성되지 않음
4. 축약 SHA / 미고정 / 로컬 경로	`owner/repo#a1b2c3d` (7자) `owner/repo` `./local-skills/lint`	무시됨 (Unchanged)	무시됨 (Unchanged)	7~8자리 짧은 커밋 해시를 적어두면 Dependabot이 인식하지 못하고 건너뛰므로 반드시 40자 전체 SHA나 태그를 써야 함

3. `.github/dependabot.yml` 및 CI 검증 설정 패턴

단일 저장소 루트에 apm.yml과 apm.lock.yaml이 있는 경우, 아래와 같이 .github/dependabot.yml에 package-ecosystem: "apm" 항목을 추가한다. 모노레포에서 하위 폴더마다 독립된 apm.yml을 쓴다면 각 directory를 개별 항목으로 나열해야 한다.

또한 Dependabot이 연 PR에서 누군가 apm.yml만 수정하고 apm.lock.yaml이나 MCP 설정 동기화를 누락하는 일을 막으려면, CI 워크플로에서 --frozen 플래그로 일관성을 강제하는 편이 안전하다.

4. 로컬 Python으로 검증하는 `apm.yml` 핀 형식 및 락파일 누락 진단기

팀 저장소에 Dependabot APM 설정을 붙이기 전에, 현재 apm.yml의 의존성 문자열들이 실제로 업데이트 대상인지(혹은 축약 SHA나 락파일 누락으로 무시되는지) 사전 점검하는 Python 스크립트다.

직접 실행해 확인한 범위

로컬 Python 환경에서 다섯 가지 대표 표기 사례를 검증했다.

가상 패키지 세맨틱 태그(acme/agent-skills/code-review#v1.2.0): manifest_tag_bumped_to_latest_release로 분류되며 apm.lock.yaml이 함께 재생성된다.

7자리 축약 커밋 SHA(acme/agent-skills#a1b2c3d): 실무에서 흔히 쓰는 짧은 커밋 해시는 abbreviated_sha_not_supported로 무시됨을 검출한다.

40자리 전체 커밋 SHA: 정상 업데이트(sha40_to_latest_release_tag_with_comment) 대상으로 분류된다.

락파일 없는 브랜치 핀(acme/agent-skills#main, has_lockfile=False): Dependabot이 새 락파일을 생성하지 않으므로 branch_pin_requires_existing_apm_lock_yaml 경고를 반환한다.

락파일 있는 브랜치 핀(has_lockfile=True): 매니페스트는 유지한 채 락파일 커밋만 갱신하는 lockfile_only_commit_bump로 판정된다.

5. 도입 전 실무 점검 체크리스트

apm.lock.yaml 버전 관리 포함 여부 확인: Dependabot은 없는 락파일을 새로 만들지 않는다. apm lock으로 생성한 apm.lock.yaml을 Git에 먼저 커밋해 두어야 PR에서 재현 가능한 해시 변경을 함께 검토할 수 있다.

축약 SHA를 40자 전체 SHA 또는 릴리스 태그로 교체: apm.yml에 7~8자리 짧은 커밋 해시가 남아 있다면 Dependabot이 건너뛰므로 전체 40자 SHA나 #vX.Y.Z 태그로 수정한다.

스킬·프롬프트 PR의 프롬프트 인젝션 수동 리뷰: APM 버전 업데이트 PR은 보안 스캔을 거친 결과가 아니다. 업스트림 스킬의 마크다운 지침이나 스크립트에 승인 우회·외부 전송 지시가 추가되지 않았는지 반드시 파일 diff를 읽고 병합해야 한다.

참고 자료

GitHub Changelog — Dependabot version updates support Agent Package Manager (November 3, 2026)

GitHub Docs — Dependabot supported ecosystems and repositories (APM)

GitHub dependabot-core Issue #14350 — Support microsoft/apm (Agent Package Manager)

확인 기준일: November 6, 2026

English version: GitHub Dependabot for Agent Package Manager (APM): Pinning Rules, apm.lock.yaml Regeneration, and Review Boundaries