Markdown으로 만든 AI 자동화, 바로 Actions에 올려도 될까? 6칸 실행 경계 카드

읽는 시간 약 8분 · GitHub Actions에서 AI workflow를 운영하기 전 확인할 경계

핵심 요약

• GitHub의 Agentic Workflows는 Markdown으로 정의하고 GitHub Actions workflow로 실행할 수 있는 방식입니다. 따라서 문서 검토와 실행 검토를 분리하지 않는 편이 좋습니다.
• 처음에는 PR 본문을 읽고 코멘트 초안만 제안하는 상태처럼 영향이 작은 흐름으로 시작하세요.
• 저장소 쓰기 권한, 새 action, 외부 목적지, 다음 자동화가 소비하는 artifact가 추가되면 기존 승인을 연장하지 말고 카드를 다시 검토하세요.
• 비밀값은 모델 입력, 로그, artifact로 가는 경로를 따로 확인해야 합니다. 설정 이름만 보고 안전하다고 판단하면 부족합니다.

왜 문서 검토만으로는 부족할까요?

GitHub의 Agentic Workflows 설명은 Markdown 기반 정의와 GitHub Actions 실행의 연결을 안내합니다. 이 조합에서는 지시문 문장만 잘 읽는 것으로 충분하지 않습니다. 어떤 이벤트가 실행을 열고, 어떤 입력을 읽고, 토큰이 무엇을 할 수 있으며, 결과가 누군가의 판단인지 다음 자동화의 입력인지까지 하나의 흐름으로 봐야 합니다.

특히 AI workflow는 자연어 결과를 만들 수 있습니다. 그 결과가 단순한 검토용 초안일 때와 PR을 만들거나 외부 티켓을 여는 다음 단계의 재료일 때는 운영 부담이 다릅니다. FLOWIT의 실무 기준은 기능 수가 아니라 결과가 실제로 바꾸는 범위와 사람이 멈출 수 있는 지점입니다.

배포 전에 채우는 6칸 실행 경계 카드

아래 카드는 특정 제품 설정을 대신하지 않습니다. 저장소의 현재 설정과 조직 정책을 함께 확인하기 위한 검토 기록입니다.

1. 1. 트리거와 입력
   어떤 이벤트에서 시작하며 PR 본문, 이슈 텍스트, 파일 목록 중 무엇을 읽는지 한 문장으로 적습니다.
2. 2. 최소 권한
   작업에 꼭 필요한 토큰 권한만 적고, 설정에 실제로 같은 범위가 적용되는지 확인합니다.
3. 3. 비밀값 규칙
   비밀값을 쓰는지, 모델 입력·로그·artifact로 향하는 경로가 없는지 구분해 적습니다.
4. 4. 허용 변경 범위
   코멘트 초안, 라벨 제안처럼 가능한 동작과 코드·릴리스·권한 변경처럼 금지할 동작을 나눕니다.
5. 5. 산출물 소비자
   사람이 읽는 초안인지, 다른 workflow가 읽는 artifact인지, 외부 서비스가 받는 요청인지 명확히 적습니다.
6. 6. 사람 인수·중단 조건
   모호한 결과, 오류, 새 권한 요청, 외부 전달 요청에서 누가 확인하고 언제 멈추는지 정합니다.

PR 라벨 요약으로 작게 시작하는 예시

처음부터 PR 생성이나 외부 티켓 생성으로 시작할 필요는 없습니다. 예를 들어 PR 본문과 변경 파일 목록을 읽고, “검토가 필요한 영역”을 코멘트 초안으로 제안하는 workflow를 생각해 보겠습니다. 이 예시는 실제 저장소의 결과나 공식 권장 구성이 아니라, 카드 작성 방식을 설명하기 위한 운영 예시입니다.

• 입력: PR 제목·본문과 허용된 파일 목록만 읽습니다.
• 허용 동작: 사람이 확인할 코멘트 초안을 만들고, 자동 반영은 하지 않습니다.
• 금지 동작: 코드 수정, 릴리스 생성, 새 webhook 호출, 외부 티켓 생성은 하지 않습니다.
• 중단: 입력 범위 밖 파일이 필요하거나 새 권한이 필요하면 결과를 보류하고 담당자에게 넘깁니다.

이렇게 시작하면 비용도 비교적 예측하기 쉽습니다. 실행 이벤트와 읽는 입력을 좁히면 불필요한 호출과 검토량을 줄일 수 있고, 실패했을 때 영향을 받는 범위도 작아집니다. 반대로 “요약이 잘 된다”는 이유만으로 쓰기와 외부 전달을 붙이면, 결과의 품질을 확인하는 운영 절차가 뒤늦게 따라오게 됩니다.

읽기·초안·쓰기·외부 전달을 같은 위험도로 보지 않기

GitHub Actions 보안 강화 문서는 권한과 외부 의존성을 함께 검토할 필요를 설명합니다. 위 표의 핵심은 “허용/차단”이라는 두 상태가 아니라, 결과가 어디서 소비되는지에 따라 확인 지점을 달리 두는 것입니다.

언제 재검토 상태로 돌릴까요?

다음 변화는 기존 카드에 한 줄을 덧붙이는 수준이 아니라, 경계를 다시 확인할 신호입니다.

• 새 action 또는 제3자 의존성을 추가할 때
• 읽기 전용 토큰에 쓰기 권한을 더할 때
• 새로운 외부 목적지나 webhook을 연결할 때
• artifact를 사람이 아니라 다음 자동화가 소비하게 만들 때
• 비밀값을 참조하거나 로그·산출물 경로가 바뀔 때

GitHub Actions의 비밀값 사용 문서를 현재 저장소 구성과 함께 확인하세요. 중요한 점은 어떤 구성에서도 비밀값 노출이 자동으로 막힌다고 가정하지 않는 것입니다. 사용 여부, 전달 경로, 출력 위치를 실제 workflow 기준으로 확인해야 합니다.

배포 전 체크리스트

• 트리거와 읽는 입력을 한 문장으로 설명할 수 있나요?
• workflow 설정과 카드에 적은 최소 권한이 실제로 일치하나요?
• 비밀값이 모델 입력, 로그, artifact로 가는 경로를 금지하거나 분리했나요?
• 허용 변경과 금지 변경이 구체적인 동사로 나뉘어 있나요?
• 각 결과물을 사람, 다른 자동화, 외부 서비스 중 누가 소비하는지 적었나요?
• 오류·모호함·새 권한 요청에서 담당자에게 넘기거나 중단하는 조건이 있나요?

카드를 통과했다고 해서 모든 위험이 사라지는 것은 아닙니다. 다만 도입 판단을 “AI가 잘 요약하는가”에서 “이 실행이 어떤 범위에서 누구에게 영향을 주는가”로 옮길 수 있습니다. 이어서 GitHub Issue 자동 처리의 승인과 되돌리기, 도구 호출의 승인 경계, 민감 파일 제외 확인도 함께 살펴보시면 좋습니다.

자주 묻는 질문

단순 요약 workflow도 카드가 필요한가요?

네. 읽기와 초안만 만드는 작은 흐름이라도 무엇을 읽고 결과를 누가 채택하는지 적어 두면, 나중에 쓰기나 외부 전달을 붙일 때 변경 지점을 놓치지 않을 수 있습니다.

artifact를 다음 자동화에 넘겨도 되나요?

가능한지와 별개로, 다음 소비자가 무엇을 실행하는지 분리해 검토하는 편이 좋습니다. 사람이 읽는 보고서와 후속 작업의 입력은 영향 범위가 다릅니다.

새 action을 추가하면 무엇을 먼저 봐야 하나요?

새 action이 읽는 입력, 필요한 권한, 외부 통신, 출력물을 먼저 확인하고 6칸 카드를 재검토하세요. 기존 승인 범위가 자동으로 확장된다고 보면 안 됩니다.

조직의 보안 정책이 있다면 카드가 필요 없나요?

아닙니다. 조직 정책은 기준선이고, 카드는 특정 workflow가 그 기준선 안에서 실제로 무엇을 실행하는지 연결해 보는 작업 기록입니다.

참고 자료

• GitHub — About GitHub Agentic Workflows: Markdown 정의와 Actions 실행의 제품 맥락
• GitHub — Develop agentic workflows in GitHub Actions: Actions에서 workflow를 개발하는 출발점
• GitHub — Security hardening for GitHub Actions: 권한과 외부 의존성 검토의 보안 맥락
• GitHub — Using secrets in GitHub Actions: 비밀값을 다루는 workflow에서 확인할 경로