GitLab CI에 AI 에이전트를 연결할 때 점검할 5가지

CLAUDE.md나 AGENTS.md는 코딩 에이전트에게 무엇을 하라고 지시하는 파일입니다. 이 파일은 마크다운 문서라서 단순 문서로 취급되기 쉬운데요. 그러나 CI에서 에이전트가 읽는 순간, 이 파일은 문서를 넘어 파이프라인 동작에 영향을 주는 강력한 파일이 됩니다.

문제는 이 파일이 무방비 상태로 놓여 있다는 것입니다. .gitlab-ci.yml은 파이프라인 설정 파일이라는 인식이 있어 대개 리뷰를 거치지만, CLAUDE.md는 확장자만 보면 README와 다를 게 없어 리뷰 대상에서 빠지기 쉽습니다. 파이프라인을 움직이는 파일이 됐는데도, 여전히 단순 문서로 취급하는 셈이죠.

Claude Code나 Codex를 GitLab CI에 연결하면, Job이 저장소를 체크아웃한 뒤 에이전트를 실행합니다. 이때 Claude Code는 워크스페이스의 CLAUDE.md를, Codex는 AGENTS.md를 읽고 작업합니다. 그런데 저는 테스트용 프로젝트에서 이 파일을 아무 승인 절차 없이 수정할 수 있는 상태임을 확인했습니다.

이는 Merge request(MR) 하나로 에이전트에게 전달되는 지시를 바꿀 수 있고, 그 변경은 아무도 검토하지 않는다는 뜻입니다. 리뷰 기준을 무력화하는 문장 한 줄이 들어와도, 문서 수정으로 인식돼 그냥 지나칠 수 있습니다. 허용 도구를 제한해도 막히지 않습니다. 리뷰 기준을 낮추라는 지시는 따로 실행하는 명령이 없으니 도구 제한이 막을 것이 없습니다.

에이전트를 CI에 연결했다면 CLAUDE.md나 AGENTS.md도 함께 관리해야 합니다. 에이전트 설정 파일이 무엇인지 목록화돼 있는지, 그 파일이 CODEOWNERS에 등록돼 있는지, 승인 규칙이 실제로 작동하는지, 변경을 탐지하는 CI Job이 있는지, 에이전트 크리덴셜이 보호된 변수인지 점검해야 하죠. 이 글에서는 GitLab에서 이 다섯 가지를 점검하는 방법을 실습으로 살펴보겠습니다.

실습 환경

본격적인 점검에 앞서 실습 환경과 저장소의 상태를 정리하겠습니다.

이 글의 실습은 다음 환경에서 진행했습니다.

우리 저장소는 지금 어떤가

실습 전 제 저장소 상태를 기록하면 다음과 같습니다. 다섯 가지 기준으로 먼저 점검했으며, 조치를 마친 뒤 같은 기준으로 다시 점검해 무엇이 달라졌는지 비교하겠습니다.

점검 결과, 제 저장소는 다섯 기준 중 해당하는 것이 하나도 없었습니다(0/5). 새 프로젝트이니 당연한 결과죠. 다만 CLAUDE.md를 만드는 데는 1분이면 충분한 반면, 그 파일을 CODEOWNERS에 등록하고 보호 브랜치 설정을 활성화하는 절차는 별도로 거쳐야 하는데요. 에이전트를 도입할 때 이 절차를 함께 계획하지 않았다면, 기존에 운영 중인 저장소에서도 CLAUDE.md는 아무 승인 절차 없이 수정할 수 있는 상태일 수 있습니다.

1. 에이전트 설정 파일 목록화하기

첫 번째 점검은 에이전트가 저장소에서 어떤 파일을 읽는지 정리하는 것입니다. 이 목록이 있어야 다음 단계에서 승인 규칙을 설정할 파일과 변경을 탐지할 파일을 정할 수 있습니다.

1. 팀이 쓰는 코딩 에이전트를 확인합니다.

   Claude Code와 Codex는 읽는 파일이 다릅니다. 어떤 에이전트를 CI에 연결했는지 먼저 확인합니다.

2. 그 에이전트가 읽는 파일을 확인합니다.

   에이전트	읽는 파일
   Claude Code	CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md, .claude/rules/*.md, 하위 디렉터리의 CLAUDE.md
   Codex	루트부터 작업 디렉터리까지 각 디렉터리의 AGENTS.md

   Claude Code는 CLAUDE.md 하나만 읽지 않습니다. 하위 디렉터리의 CLAUDE.md도 해당 디렉터리 파일을 읽을 때 포함됩니다. Codex도 프로젝트 루트에서 작업 디렉터리까지 각 디렉터리를 확인하고 찾은 파일을 순서대로 읽습니다.

   📝 Note

   CLAUDE.md에 @docs/rules.md처럼 다른 파일 경로를 적으면, 에이전트는 그 파일의 내용을 CLAUDE.md의 일부로 읽습니다. 따라서 CLAUDE.md는 그대로 두고 docs/rules.md만 바꿔도 에이전트에게 전달되는 지시가 달라집니다. import 대상 파일도 목록에 포함해야 합니다.

3. 저장소에서 해당 파일을 찾아 기록합니다.

   저장소 전체를 검색해 위 파일이 어디에 있는지 확인하고, 경로를 목록으로 남깁니다. 이 목록은 CODEOWNERS에 등록할 파일 목록이 됩니다.

2. CODEOWNERS에 등록하기

목록이 있으니 이제 그 파일에 승인 절차를 추가합니다. GitLab에서는 CODEOWNERS로 이 절차를 만들 수 있습니다.

CODEOWNERS는 저장소의 파일별 소유자를 지정하는 파일입니다. 이 파일에 CLAUDE.md와 그 소유자를 등록해 두면, 누군가 CLAUDE.md를 수정한 MR을 만들 때 GitLab이 그 MR에 Code Owners 승인 규칙을 자동으로 추가합니다. 여기에 보호 브랜치 설정에서 Code Owner 승인을 활성화하면, 등록된 소유자가 승인해야만 해당 MR을 merge할 수 있습니다.

적용 전 상태 확인하기

먼저 CODEOWNERS를 적용하기 전 상태를 확인합니다. CLAUDE.md를 한 줄 수정하고 새 브랜치로 커밋한 뒤, 그 브랜치로 MR을 만듭니다. GitLab 웹 편집기에서 커밋할 때 “Create a merge request for this change”를 체크하면 한 번에 됩니다.

MR 생성 화면 아래쪽 Reviewers 항목을 보면 "Approvals are optional"이라고 표시됩니다. 승인이 필요 없다는 뜻입니다. 파이프라인 동작을 바꾸는 파일인데도 아무 절차 없이 merge할 수 있는 상태입니다.

CODEOWNERS 적용 전. 승인이 선택 사항으로 표시됨

CODEOWNERS 만들기

CLAUDE.md를 수정한 MR에 승인이 필요 없는 상태를 확인했으니, 이제 CODEOWNERS 파일을 만들어 승인 규칙을 설정하겠습니다.

1. CODEOWNERS 파일을 둘 위치를 정합니다.

   CODEOWNERS 파일은 루트, docs/, .gitlab/ 세 위치 중 한 곳에 둘 수 있습니다. GitLab은 이 순서로 찾아 처음 발견한 파일만 저장소에 적용합니다. 두 곳 이상에 파일을 두면 나머지는 무시됩니다. 이 실습에서는 .gitlab/CODEOWNERS에 만들었습니다.

2. CODEOWNERS 파일에 승인 규칙을 작성합니다.

   GitLab 웹 편집기에서 새 파일을 만들고 파일명을 .gitlab/CODEOWNERS로 입력하면 폴더가 함께 생성됩니다. 파일 내용은 다음과 같이 작성합니다.

   plain

   [Agent configuration]
   CLAUDE.md @reviewer
   AGENTS.md @reviewer
   

   첫 줄은 섹션 이름이고, 그 아래 각 줄이 '파일 경로 소유자' 형식입니다. 이 각 줄이 승인 규칙 하나입니다. CLAUDE.md @reviewer는 "CLAUDE.md를 바꾸는 MR은 @reviewer가 승인해야 한다"는 뜻입니다. @reviewer 자리에 실제 GitLab 사용자명(Username)을 넣습니다.

   실습에서는 두 파일만 등록했습니다. 실제 적용 시에는 목록으로 정리한 에이전트 설정 파일을 모두 등록해야 합니다. .claude/** @reviewer처럼 디렉터리 패턴을 쓰면 하위 파일까지 한 번에 잡힙니다.

   📝 Note

   @reviewer 자리에 프로필의 Full name을 적으면 인식되지 않습니다. GitLab 사용자명은 프로필 화면에서 @ 뒤에 표시되는 값입니다.

   소유자는 본인이 아닌 다른 사람으로 지정하는 것을 권장합니다. 소유자가 본인 한 명뿐이면 승인 규칙이 적용되지 않습니다.

3. CODEOWNERS 문법 검사 결과를 확인합니다.

   파일을 커밋한 뒤 저장소에서 열면 GitLab이 CODEOWNERS 문법을 검사해 결과를 보여줍니다. 'Syntax is valid'가 표시되면 파일 형식이 올바른 것입니다. 다만 이 검사는 파일 문법과 소유자의 권한까지만 확인합니다. 보호 브랜치에서 Code Owner 승인이 활성화돼 있는지는 보지 않기에 승인 규칙이 실제로 작동하는지는 별개 문제입니다.

   📝 Note

   이 문법 검사는 GitLab 18.2 이상에서 제공됩니다. Self-managed 환경에서는 버전을 확인하세요.

3. 승인 규칙이 실제로 작동하게 만들기

CODEOWNERS는 규칙을 정의할 뿐이며, 그 규칙을 강제하는 스위치는 보호 브랜치 설정에 있습니다. 이 스위치를 켜고, MR을 생성해 실제로 merge가 막히는지 확인하겠습니다.

보호 브랜치에서 켜기

CODEOWNERS 파일을 만들어 유효하다는 것까지 확인했지만, 이것만으로는 승인이 강제되지 않습니다. 보호 브랜치 설정에서 Code Owner 승인을 활성화해야 등록한 소유자가 승인하기 전에는 merge할 수 없게 됩니다.

1. 보호 브랜치 설정으로 이동합니다.

   plain

   Settings > Repository > Protected branches
   

   📝 Note

   현재 GitLab은 이 설정을 Branch rules로 옮기고 있습니다. Protected branches 항목이 보이지 않으면 Settings > Repository > Branch rules에서 해당 브랜치의 상세 화면을 열고 Require code owner approval 토글을 켜세요.

2. 대상 브랜치의 Code owner approval 토글을 켭니다.

   main 행의 맨 오른쪽 Code owner approval 열에 있는 토글을 켭니다. 별도의 저장 버튼 없이 바로 적용됩니다.

   보호 브랜치에서 Code owner approval을 활성화한 상태

3. Allowed to push and merge를 확인합니다.

   같은 행의 Allowed to push and merge 값을 확인합니다. 이 값에 설정된 역할은 MR 없이 브랜치에 직접 push할 수 있어 Code Owner 승인을 건너뛰게 됩니다. 예를 들어, Maintainer로 설정돼 있다면 Maintainer는 승인 없이 CLAUDE.md를 바꿀 수 있습니다.

   📝 Note

   CLAUDE.md를 포함한 모든 변경이 MR을 거치게 하려면 이 값을 No one으로 바꿉니다. 값을 비워두면 push 제한이 걸리지 않아서 반드시 No one을 선택해야 합니다.

4. 두 설정이 모두 활성화됐는지 확인합니다.

   CODEOWNERS 파일과 Code owner approval 토글은 독립된 설정입니다. 둘 다 활성화한 뒤에 만든 MR부터 승인 규칙이 적용됩니다.

적용 확인하기

이제 승인 규칙이 실제로 작동하는지 확인합니다.

1. MR을 새로 만듭니다.

   CLAUDE.md를 한 줄 수정하고 새 브랜치로 커밋한 뒤 MR을 만듭니다.

   📝 Note

   설정 전에 열어둔 MR은 재사용하지 마세요. Code Owner 승인 규칙은 MR이 생성되는 시점에 결정되기에 기존 MR에는 새 설정이 반영되지 않습니다.

2. MR 페이지에서 승인 위젯을 펼칩니다.

   MR을 만든 뒤 MR 페이지로 이동합니다. 파이프라인 상태 아래 승인 위젯의 오른쪽 **∨**를 클릭해 펼칩니다.

   📝 Note

   MR 생성 화면의 Approval rules에는 Code Owners 항목이 표시되지 않을 수 있습니다. 실습에서는 생성 화면에 나타나지 않던 이 항목이 MR 페이지에서는 표시됐습니다. 확인은 MR 페이지에서 하세요.

3. Code Owners 항목의 상태를 확인합니다.

   승인 위젯 표시	판정
   Code Owners 항목에 “0 of 1”처럼 승인 수가 표시됨	승인 규칙이 작동하는 상태
   Code Owners 항목이 있지만 Optional로 표시됨	규칙은 걸렸으나 강제되지 않음
   Code Owners 항목이 있지만 Auto approved로 표시됨	승인할 사람이 없음
   Code Owners 항목이 없음	규칙이 걸리지 않음

   승인 규칙이 작동하는 상태. Code Owners 항목에 “0 of 1”이 표시되고 Merge가 승인 대기로 막힘

4. Merge가 승인 대기로 막혀 있는지 확인합니다.

   승인 위젯 문구가 “Requires 1 approval from Code Owners”로 바뀌고, Merge 영역에 “All required approvals must be given”이 표시되면 규칙이 작동하는 것입니다. 반면에 승인 위젯이 “Approval is optional”이고 Merge 버튼이 활성 상태라면 규칙과 무관하게 merge할 수 있는 상태입니다.

4. 변경을 파이프라인에 노출하기

지금까지 승인이 강제되는 것을 확인했습니다. 다만 CODEOWNERS는 승인을 요구할 뿐, 에이전트 설정 파일이 바뀌었다는 사실을 눈에 띄게 알리거나 무엇을 봐야 하는지 알려주지는 않습니다.

에이전트 설정 파일이 바뀐 MR에서만 경고를 띄우는 Job을 추가하겠습니다.

1. .gitlab-ci.yml에 Job을 추가합니다.

   yaml

   stages:
     - review
   
   agent-config-review:
     stage: review
     image: alpine:3.20
     variables:
       GIT_DEPTH: 0
     rules:
       - if: $CI_PIPELINE_SOURCE == "merge_request_event"
         changes:
           - CLAUDE.md
           - AGENTS.md
           - .claude/**/*
         allow_failure: true
     before_script:
       - apk add --no-cache git
     script:
       - |
         BASE="origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
         PATHS="CLAUDE.md AGENTS.md .claude"
   
         git fetch --quiet origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
   
         echo "이 Merge request는 에이전트 설정 파일을 변경합니다."
         echo ""
         echo "── 변경된 파일 ──"
         git diff --name-only "$BASE"...HEAD -- $PATHS
         echo ""
         echo "── 변경 내용 ──"
         git diff "$BASE"...HEAD -- $PATHS
         echo ""
         echo "리뷰어 확인 사항"
         echo "  1. 에이전트에게 새로 허용되는 동작이 있는가"
         echo "  2. 외부로 데이터를 보내는 지시가 있는가"
         echo "  3. 기존 제약을 해제하는 문구가 있는가"
   
         exit 1
   

   changes: 목록과 스크립트의 PATHS 변수는 앞서 정리한 에이전트 설정 파일 목록에 맞게 조정합니다. 다음 세 가지 설정은 각각 이유가 있으니 바꾸기 전에 확인하세요.

   설정	이유
   if:와 changes:를 함께 사용	changes:만 쓰면 브랜치 파이프라인에서 최근 push만 확인해 놓칠 수 있습니다
   GIT_DEPTH: 0	새로 만든 프로젝트는 기본적으로 최근 20개 커밋만 가져옵니다(Git shallow clone). 그 안에 대상 브랜치와의 기준 커밋이 없으면 차이를 비교할 수 없어 전체 이력을 가져오도록 설정합니다
   allow_failure: true + exit 1	Job을 실패시켜 MR에 표시하되, 파이프라인은 통과시킵니다

   📝 Note

   사내 CI 템플릿을 쓰고 있다면 주의하세요. include:로 가져온 규칙은 MR 파이프라인 조건을 충족하지 못합니다. 이 Job의 rules:는 .gitlab-ci.yml에 직접 작성해야 합니다.

2. CLAUDE.md를 수정한 MR을 만들어 경고를 확인합니다.

   파이프라인이 "passed with warnings"로 표시되면 Job이 작동한 것입니다. 그 아래 승인 요구와 Merge blocked는 앞서 설정한 승인 규칙입니다. 경고는 파이프라인이 띄우고, 차단은 승인 규칙이 맡는 구조입니다.

   📝 Note

   이 경고는 Job 스크립트 마지막 줄의 exit 1이 만듭니다. 이 줄이 없으면 Job이 단순 성공으로 끝나 경고 없이 성공으로만 표시됩니다.

   에이전트 설정 파일 변경이 파이프라인 경고로 표시되고, 승인 규칙이 merge를 막고 있는 상태

   Job 로그를 열면 변경된 파일명과 diff, 리뷰어 확인 사항이 출력됩니다. 리뷰어 확인 사항을 출력하는 이유는 파일이 바뀌었다는 사실만으로는 무엇을 확인해야 하는지 알기 어렵기 때문입니다.

   Job 로그에 출력된 변경 파일, diff, 리뷰어 확인 사항. 마지막 줄의 exit code 1이 파이프라인 경고를 만듦

   📝 Note

   이 Job은 경고용입니다. merge를 막는 역할은 앞서 설정한 승인 규칙이 맡습니다. allow_failure: true를 빼면 이 Job은 항상 실패해서 “Pipelines must succeed”가 활성화된 프로젝트에서는 에이전트 설정 파일을 바꾸는 MR을 merge할 수 없게 됩니다.

5. 크리덴셜을 보호된 변수로

지금까지는 에이전트 설정 파일이 바뀌는 것을 알리고 막는 조치였습니다. 남은 하나는 그 파일이 바뀌더라도 에이전트가 닿을 수 있는 범위를 좁히는 것입니다.

에이전트를 CI에서 실행하려면 API 키가 필요하고, 이 키는 CI/CD 변수로 저장합니다. 변수에는 Protect 옵션이 있습니다. 이 옵션을 활성화하면 보호 브랜치나 보호 태그에서 실행되는 파이프라인에서만 변수를 사용할 수 있습니다. 일반 브랜치에서 올린 MR 파이프라인에는 실리지 않습니다. 소스 브랜치까지 보호 브랜치인 MR만 예외입니다.

1. CI/CD 변수를 확인합니다.

   plain

   Settings > CI/CD > Variables
   

   에이전트 API 키가 변수로 등록돼 있는지, 그 변수에 Protected 배지가 있는지 확인합니다. 실습에서는 Claude Code 통합에서 사용하는 변수명인 ANTHROPIC_API_KEY로 테스트용 값을 등록했습니다.

   Protect를 켜지 않은 상태. 모든 브랜치의 파이프라인에서 사용할 수 있음

2. Protect와 Mask를 활성화합니다.

   plain

   변수 오른쪽 Edit
   → Visibility에서 Masked 선택
   → Protect variable 체크
   → Save changes
   

   Protect는 변수를 쓸 수 있는 파이프라인을 제한하고, Mask는 Job 로그에 값이 그대로 찍히는 것을 막습니다. 역할이 다르므로 함께 활성화합니다.

   Protected와 Masked를 적용한 상태. 아래 Group variables 섹션에서 상위 그룹 변수도 확인할 수 있음

   📝 Note

   Mask는 실수로 인한 노출을 줄일 뿐입니다. GitLab도 화면 안내에서 마스킹이 악의적 사용자의 변수 접근을 막는 보장된 방법은 아니라고 밝히고 있습니다.

3. 상위 그룹에서 상속되는 변수도 확인합니다.

   같은 화면 아래 Group variables (inherited) 섹션에 상위 그룹의 변수가 표시됩니다. 프로젝트 변수만 보면 놓칠 수 있습니다. 여기에도 에이전트 크리덴셜이 있다면 그룹 설정에서 같은 방식으로 Protect를 활성화해야 합니다.

다시 점검하기

처음에 점검했던 다섯 기준으로 다시 점검해 무엇이 달라졌는지 살펴봤습니다.

다섯 기준을 모두 충족했습니다. 다만 설정 화면에서 체크만 해서 기준을 충족할 수 있는 것은 아니었는데요. 설정과 작동 사이에 한 단계 조치가 더 필요했습니다.

맺음말

지금까지 CI에 연결한 코딩 에이전트의 설정 파일이 왜 관리 대상이 되는지, GitLab에서 이를 점검하는 다섯 가지 방법을 실습으로 살펴봤습니다. 정리하면 다음과 같습니다.

1. CLAUDE.md와 AGENTS.md는 확장자만 보면 문서지만, CI에서 에이전트가 읽는 순간 파이프라인 동작을 결정하는 파일이 됩니다. 저장소 쓰기 권한만 있으면 MR 하나로 지시를 바꿀 수 있고, 리뷰 기준을 낮추는 문장은 실행하는 명령이 없어 도구 제한으로도 걸러지지 않습니다. 그래서 파일 자체에 승인 절차가 필요합니다.
2. 점검은 목록에서 시작합니다. Claude Code는 CLAUDE.md 외에 .claude/ 아래 파일과 하위 디렉터리의 CLAUDE.md, import한 파일까지 읽고, Codex는 디렉터리마다 AGENTS.md를 읽습니다. 어떤 파일이 읽히는지 모르면 승인 규칙도 변경 탐지도 걸 수 없습니다.
3. 승인은 두 설정이 만나야 강제됩니다. CODEOWNERS가 규칙을 정의하고, 보호 브랜치의 Code owner approval 토글이 그 규칙을 활성화합니다. 문법 검사를 통과해도 토글이 꺼져 있으면 규칙은 Optional로 남고, 소유자가 MR 작성자 본인뿐이면 승인할 사람이 없어 역시 강제되지 않습니다. 작동 여부는 MR을 새로 열어 승인 위젯에 "0 of 1"이 뜨는지로 확인합니다.
4. 승인은 막기만 하고 알리지는 않습니다. 에이전트 설정 파일이 바뀐 MR에서만 실행되는 CI Job이 변경 파일과 diff, 리뷰어가 볼 항목을 로그에 남기고 exit 1로 경고를 띄웁니다. allow_failure: true와 짝을 이뤄야 경고에 그치고, 차단은 승인 규칙의 몫입니다.
5. 파일이 바뀌더라도 에이전트가 닿는 범위는 좁힐 수 있습니다. API 키를 Protected 변수로 두면 보호 브랜치 파이프라인에서만 쓰이고, 일반 브랜치의 MR 파이프라인에는 실리지 않습니다. Mask는 로그 노출을 줄이는 보조 장치이고, 상위 그룹에서 상속되는 변수도 따로 확인해야 합니다.

참고 자료

1. Jafar Isbarov, Umid Suleymanov, Ilia Shumailov, Murat Kantarcioglu, "GitInject: Real-World Prompt Injection Attacks in AI-Powered CI/CD Pipelines", arXiv:2606.09935, 2026, https://arxiv.org/abs/2606.09935
2. "Manage Claude's memory", Claude Code Docs, https://code.claude.com/docs/en/memory
3. "AGENTS.md", OpenAI Developers, https://developers.openai.com/codex/guides/agents-md
4. "Code Owners", GitLab Docs, https://docs.gitlab.com/user/project/codeowners/
5. "Syntax of CODEOWNERS file", GitLab Docs, https://docs.gitlab.com/user/project/codeowners/reference
6. "Troubleshooting Code Owners", GitLab Docs, https://docs.gitlab.com/ee/user/project/codeowners/troubleshooting
7. "Protected branches", GitLab Docs, https://docs.gitlab.com/user/project/repository/branches/protected/
8. "Merge request approval rules", GitLab Docs, https://docs.gitlab.com/user/project/merge_requests/approvals/rules/
9. "Merge request pipelines", GitLab Docs, https://docs.gitlab.com/ci/pipelines/merge_request_pipelines/
10. "Specify when jobs run with rules", GitLab Docs, https://docs.gitlab.com/ci/jobs/job_rules/
11. "Customize pipeline configuration", GitLab Docs, https://docs.gitlab.com/ci/pipelines/settings/
12. "CI/CD variables", GitLab Docs, https://docs.gitlab.com/ci/variables/
13. "'Allowed to push' should be able to merge without CODEOWNERS approvals", GitLab.org / GitLab issue #419008, https://gitlab.com/gitlab-org/gitlab/-/issues/419008