AI 에이전트 거버넌스: GitLab으로 Claude Code 활동 기록하고 변경 통제하기

AI 코딩 에이전트가 개인이 쓰는 도구에서 조직의 개발 인프라로 확대되면서 에이전트를 어떻게 관리하고 통제할지에 대한 관심도 커지고 있습니다. 국내 기업도 에이전트를 도입하면서 관리 체계를 함께 마련하고 있는데요. SK텔레콤은 2026년 6월 에이전트에 사번과 소속, 직무, 권한을 주고, 에이전트를 위한 데이터·보안 접근 권한 규정을 마련하겠다고 밝혔습니다. KB국민은행은 2026년 7월 개소한 KB AI Dev 센터에서 Claude Code 같은 외부 코딩 에이전트를 개발 업무에 연결하고, 자체 개발한 '하네스'로 요구사항 정제부터 정책 검증, 사람의 승인까지 AI 작업의 전 과정을 통제하죠.

이처럼 에이전트에게 맡길 일을 정하고, 정한 범위를 지키게 하고, 에이전트가 한 일을 기록하고 검토하는 체계를 ‘AI 에이전트 거버넌스’라고 합니다. 에이전트 거버넌스가 필요한 이유는 에이전트가 사람의 권한으로 명령을 실행하고 코드를 수정하는 일이 늘수록, 사람이 작업마다 확인하는 방식만으로는 관리 공백을 막기 어렵기 때문입니다. Gartner도 2026년 10월에 2027년 전략 기술 트렌드를 발표하며, AI 시스템이 사람이 검토할 수 있는 속도보다 빠르게 소프트웨어를 생성하고 관리되지 않는 크리덴셜 경로를 만들고 있다고 지적했습니다.

오늘날 개발 플랫폼과 에이전트 도구는 에이전트 거버넌스에 필요한 기능을 확대하고 있습니다. GitLab은 2026년 10월 15일 출시한 GitLab 19.5에서 Claude Code, Cursor, Codex 같은 외부 코딩 에이전트를 AI Governance에 연결하는 기능을 베타로 선보였습니다. macOS·Linux PC에서 GitLab CLI로 한 번 설정하면, 그 PC에서 GitLab 프로젝트를 대상으로 실행한 에이전트 세션을 GitLab Duo Agent Platform 에이전트 활동과 함께 AI Governance에서 볼 수 있습니다. Claude Code와 Codex도 관리자가 정한 설정을 사용자가 바꾸지 못하게 배포하는 관리 설정 기능을 제공합니다.

이 글에서는 에이전트 거버넌스의 개념과 구축 방법, GitLab AI Governance가 에이전트 활동을 기록하는 방법을 정리하고, GitLab과 Claude Code로 에이전트 거버넌스를 구축하는 과정을 실습한 뒤, 조직에 적용할 때 유의할 점을 살펴보겠습니다.

에이전트 거버넌스란 무엇이고 어떻게 작동할까요?

에이전트 거버넌스는 정책, 통제, 기록, 검토 네 단계를 반복하며 작동합니다. 조직은 에이전트 도구 설정과 개발 플랫폼 기능으로 에이전트 거버넌스를 구축할 수 있습니다.

에이전트 거버넌스는 에이전트의 작업 범위를 정하고 시스템으로 지키게 하는 체계입니다

에이전트 거버넌스는 조직이 에이전트가 할 수 있는 일을 규칙으로 정해 시스템으로 지키게 하고, 에이전트의 작업 기록을 보고 규칙을 고쳐 나가는 체계입니다. 이 체계가 있으면 조직은 에이전트에게 맡기는 일을 늘리면서도, 에이전트 활동이 정해진 규칙을 벗어나지 않도록 질서 있게 관리할 수 있죠.

에이전트 거버넌스는 크게 네 단계로 나눠 볼 수 있는데요. 조직이 에이전트가 해도 되는 일과 하면 안 되는 일을 정하면(정책), 시스템이 이 정책을 어기는 작업은 자동으로 차단하고, 정책에 없는 작업은 실행 전에 사람의 승인을 받게 합니다(통제). 시스템은 허용된 작업과 차단된 작업을 모두 기록으로 남기죠(기록). 조직은 이 기록을 보고 정책이 너무 느슨하거나 지나치게 엄격하지 않은지 검토해 수정하고(검토), 수정한 정책으로 이 네 단계를 반복합니다.

에이전트 거버넌스 네 단계가 작동하는 방식

에이전트 거버넌스는 에이전트 도구 설정과 개발 플랫폼 기능으로 구축합니다

에이전트 거버넌스의 네 단계는 각각 에이전트 도구에서 할 일과 개발 플랫폼에서 할 일로 나뉩니다. 명령 실행처럼 PC나 CI 러너에서 진행하는 작업은 에이전트 도구 설정으로, 코드 반영처럼 개발 플랫폼을 거쳐 진행하는 작업은 개발 플랫폼 기능으로 관리합니다. 에이전트 도구로 Claude Code와 Codex를, 개발 플랫폼으로 GitLab을 예로 들어 에이전트 거버넌스 구축 방법을 알아보겠습니다.

에이전트 거버넌스 네 단계에서 에이전트 도구와 GitLab이 맡는 일

1. 정책을 에이전트 도구·개발 플랫폼 설정에서 규칙으로 정의합니다

   에이전트가 해도 되는 일과 하면 안 되는 일을 에이전트 도구와 개발 플랫폼의 설정 기능에서 각각 규칙으로 작성합니다.

   • 에이전트 도구: Claude Code에서는 '관리 설정(managed settings)'에 허용·승인 필요·금지 규칙을 담아 배포하고, 사람 승인을 건너뛰는 auto·bypassPermissions 모드는 비활성화합니다. Codex에서는 requirements.toml에 허용할 승인 정책과 샌드박스 모드, 승인 필요·금지 규칙을 담아 강제 적용합니다.
   • GitLab: 보호 브랜치, MR 승인 규칙과 승인 설정, CODEOWNERS로 규칙을 정의합니다.

2. 사고로 이어질 수 있는 작업에 통제를 적용합니다

   에이전트 실행은 에이전트 도구에서, 크리덴셜 사용과 에이전트 설정 변경, 코드 반영은 개발 플랫폼에서 통제합니다.

   • 에이전트 도구: 금지한 작업은 거부하고, 정책에 없는 작업은 실행 전에 사람 승인을 받게 합니다. Claude Code에서는 권한 규칙과 Manual 모드로, Codex에서는 샌드박스와 규칙으로 이를 설정합니다. 샌드박스 안 명령은 승인 없이 실행될 수 있으니, 승인이 필요한 명령은 규칙에 따로 작성합니다.
   • GitLab
     • 크리덴셜 사용: 토큰마다 권한 범위와 만료일을 정해 제한합니다. CI에서는 작업이 실행되는 동안만 유효한 CI/CD 작업 토큰을, 외부 서비스 인증에는 ID 토큰을 사용합니다.
     • 에이전트 설정 변경: CODEOWNERS 파일에 CLAUDE.md, AGENTS.md, AGENTS.override.md, .mcp.json, .claude/, .codex/의 에이전트를 쓰는 사람이 아닌 담당자(Code Owner)를 입력합니다. 그다음, 보호 브랜치에서 Code Owner 승인을 필수로 설정해 담당자가 승인하지 않은 변경은 merge되지 않게 합니다.
     • 코드 반영: main 브랜치의 Allowed to push and merge를 No one으로 설정해 직접 push를 막습니다. 또 필수 승인, MR 작성자 승인 금지, MR에서 승인 규칙 편집 금지 설정으로 승인 없는 merge와 자기 MR 승인을 차단합니다.

3. 기록을 조직이 관리하는 시스템에 모읍니다

   에이전트 도구의 이벤트는 관측 데이터 표준인 OpenTelemetry(OTel)의 컬렉터를 거쳐 조직의 로그 시스템으로 보내고, 에이전트 세션과 승인·설정 변경 이력은 GitLab에 남깁니다.

   • 에이전트 도구: Claude Code와 Codex의 OTel 이벤트 내보내기 기능을 활성화해 도구 호출과 그 허용·거부 결과를 조직의 OTel 컬렉터로 보냅니다. Claude Code에서는 관리 설정으로, Codex에서는 requirements.toml(CLI 0.166.0 이상)로 이벤트 내보내기 설정(exporter)과 컬렉터 주소를 고정해 개인 설정으로는 바꿀 수 없게 합니다. Claude Code는 명령 내용을 기본적으로 기록하지 않기에 관리 설정에서 OTEL_LOG_TOOL_DETAILS=1도 활성화합니다. 단, Claude Code와 Codex의 이벤트에 담긴 명령과 Codex가 기본으로 보내는 도구 출력에는 민감 정보가 섞일 수 있으니 컬렉터에서 마스킹한 뒤 로그 시스템으로 보냅니다.
   • GitLab
     • 에이전트 세션: macOS·Linux PC에 GitLab CLI(glab)를 설정하면, glab이 Claude Code와 Codex의 세션 기록을 읽어 GitLab으로 보냅니다. 이 세션 기록은 AI Governance 대시보드에 외부 연결 에이전트(Externally Connected Agents)의 활동으로 나타납니다.
     • 승인·설정 변경 이력: GitLab에서는 따로 설정하지 않아도 MR 승인 이력이 각 MR에, 승인 규칙과 보호 브랜치 설정을 바꾼 이력이 감사 이벤트에 남습니다.

4. 기록을 검토해 정책을 조정합니다

   수집한 기록과 토큰 목록에서 차단된 작업, 자주 승인하는 명령, 쓰지 않는 권한을 찾아 규칙과 권한을 조정합니다.

   • 에이전트 도구: 보안 정보·이벤트 관리(SIEM) 도구나 관측 도구에서 OTel 이벤트의 판정 결과와 판정 주체를 함께 보고, 설정에 따라 자동으로 허용·거부한 에이전트 작업과 사람이 승인·거부한 에이전트 작업을 각각 확인합니다. 정상 작업이 차단됐다면 규칙을 수정하고, 자주 승인하는 명령 가운데 위험도가 낮은 명령만 범위를 좁혀 허용 규칙에 추가합니다.
   • GitLab
     • 에이전트 세션: AI Governance 대시보드와 AI 감사 이벤트 보고서에서 어느 프로젝트에 에이전트 세션이 많은지 확인하고, 세션이 많은 프로젝트부터 승인 규칙과 Code Owner 지정이 충분한지 점검합니다.
     • 크리덴셜: 토큰 목록에서 마지막 사용일이 오래된 토큰은 회수해 쓰지 않는 권한을 줄입니다.
     • 규칙 변경 반영: 검토 결과에 따라 리포지터리의 .claude/settings.json과 .codex/rules/, 원본 파일을 리포지터리에 둔 관리 설정과 requirements.toml을 수정할 때는 MR로 올리고 Code Owner 승인을 거치게 합니다. 이로써 '누가 언제 왜 바꿨는지'를 다음 검토에서 참고할 기록으로 남깁니다.

GitLab AI Governance는 에이전트 활동을 어디까지 기록할까요?

앞서 GitLab AI Governance가 PC에서 실행한 외부 연결 에이전트의 세션을 한 대시보드에 모아 보여 준다고 설명했습니다. 이 기능이 에이전트의 무엇을, 어떤 방식과 조건에 따라 기록하는지 자세히 살펴보겠습니다.

AI Governance는 조직의 에이전트 활동을 모니터링·감사·통제하는 기능입니다

AI Governance는 보안·컴플라이언스 팀이 조직 전체의 에이전트 활동을 모니터링·감사·통제할 수 있게 돕는 GitLab 기능입니다. GitLab Duo Agent Platform의 에이전트뿐만 아니라 PC에서 실행하는 Claude Code, Codex, Cursor, OpenCode 같은 외부 연결 에이전트의 세션도 한데 모으죠. 다만 통제 기능인 Tool governance는 GitLab Duo 에이전트와 GitLab MCP 서버의 도구 사용을 허용·확인·거부하는 기능이라 외부 연결 에이전트가 PC에서 실행하는 명령이나 파일 편집은 통제하지 않습니다.

대시보드와 AI 감사 이벤트 보고서로 에이전트 활동을 확인할 수 있습니다

최상위 그룹의 AI > Governance에서 대시보드와 AI 감사 이벤트 보고서를 볼 수 있습니다.

• AI Governance 대시보드: 에이전트, 세션, 도구 호출 수와 함께 많이 사용한 에이전트와 도구, 세션이 많은 프로젝트, 에이전트를 많이 사용한 사람을 보여 줍니다. Show에서 Connected를 선택하면 외부 연결 에이전트만, All agents를 선택하면 GitLab Duo Agent Platform 에이전트까지 볼 수 있습니다.
• AI 감사 이벤트 보고서: 세션별 감사 이벤트를 보여 줍니다. 세션 목록을 프로젝트나 기간 등으로 필터링하고, 세션 기록을 내려받을 수도 있습니다.

glab이 에이전트의 로컬 세션 기록을 읽어 GitLab으로 보냅니다

PC에서 glab minder setup을 실행하면, GitLab CLI(glab)가 에이전트가 PC에 남긴 세션 기록을 읽어 GitLab으로 보냅니다.

• Claude Code: 응답이 끝날 때 실행되는 Stop 훅과 세션이 끝날 때 실행되는 SessionEnd 훅이 사용자 설정 파일(~/.claude/settings.json)에 설치됩니다. 세션은 첫 응답이 끝나면 GitLab에 나타나고, 세션이 끝나면 완료로 표시됩니다.
• 백그라운드 작업: 30분마다 실행돼 훅이 놓친 기록을 보냅니다. 훅을 쓰지 않는 Codex와 Cursor의 세션은 백그라운드 작업이 로컬 세션 폴더에서 기록을 찾아 보냅니다.
• 전송 위치: 세션은 에이전트를 실행한 폴더의 GitLab 프로젝트에 기록됩니다. 폴더의 Git 리모트가 glab이 로그인한 GitLab을 가리키지 않으면 전송되지 않습니다.

glab이 에이전트 세션을 GitLab으로 보내는 경로

프롬프트와 명령은 전송되고, 도구 출력과 응답 본문은 전송되지 않습니다

Claude Code를 기준으로 GitLab에 전송되는 내용은 다음과 같습니다.

• 전송되는 내용

  • 입력한 프롬프트
  • 명령·파일 경로·편집 내용 같은 도구 호출 인자
  • 도구 호출 결과와 소요 시간
  • 응답마다 사용한 모델과 토큰 사용량
  • 세션이 끝날 때 대화 기록 파일의 체크섬
  • PC를 구분하는 해시된 머신 ID

  8KB를 넘는 프롬프트는 잘려서 전송되고, 8KB를 넘는 인자는 내용 대신 생략됐다는 표시만 전송됩니다.

• 전송되지 않는 내용: 도구 출력과 에이전트의 응답 본문은 전송되지 않습니다. 단, 도구 호출이 실패하면 출력의 처음 255자가 오류 메시지로 전송됩니다.

Premium 이상 그룹과 macOS·Linux PC에서 사용할 수 있습니다

• 요금제: 외부 연결 에이전트의 세션 수집과 AI 감사 이벤트 보고서는 Premium·Ultimate에서, 대시보드는 Ultimate에서 이용할 수 있습니다.
• Self-Managed·Dedicated: 분석용 ClickHouse를 구성해야 대시보드에 도구 호출 통계 등이 표시됩니다.
• 그룹 설정: 최상위 그룹에서 GitLab Duo Agent Platform과 Allow external agents가 활성화돼 있어야 합니다. 세션의 이벤트와 도구 호출까지 기록하려면 그룹이나 프로젝트에서 Store AI audit events도 활성화해야 합니다.
• 프로젝트와 role: GitLab.com에서는 개인 네임스페이스가 아닌 그룹 안의 프로젝트만 기록됩니다. 에이전트를 실행하는 사용자의 role은 그 프로젝트에서 Developer 이상이어야 합니다.
• PC: macOS나 Linux에서 glab 1.129.0 이상(glab minder 명령 기준)을 사용합니다.
• 열람 권한: 최상위 그룹이나 프로젝트의 Owner나 Security Manager, 또는 read_agent_artifacts 권한을 추가한 사용자 지정 role을 할당받은 사람은 대시보드와 AI 감사 이벤트 보고서를 볼 수 있습니다.

외부 연결 에이전트의 세션 수집은 GitLab 19.3에서 피처 플래그와 함께 도입됐고, GitLab 19.5부터 기본으로 활성화됐습니다. Codex와 Cursor 지원도 19.5에서 추가됐습니다.

GitLab으로 에이전트 거버넌스를 어떻게 구축할 수 있을까요?

지금부터 GitLab과 Claude Code로 에이전트 거버넌스의 네 단계를 구축해 보겠습니다. 정책과 통제 단계에는 GitLab의 CODEOWNERS, MR 승인 규칙, 보호 브랜치와 Claude Code의 실행 전 승인을, 기록과 검토 단계에는 앞서 살펴본 GitLab의 AI Governance와 프로젝트 감사 이벤트를 사용합니다.

먼저 GitLab에 정책을 설정하기 전에 Claude Code가 main 브랜치에 바로 push하는 모습을 확인하겠습니다. 그다음 정책을 설정하고 비슷한 요청이 어떻게 차단되고 기록되는지 살펴보겠습니다.

실습 환경

• GitLab.com(2026년 11월 13일 기준 GitLab 19.6.0-pre), Ultimate을 적용한 그룹
• macOS 27.0.1, GitLab CLI(glab) 1.130.0
• Claude Code 2.1.308(실습 중 2.1.323으로 자동 업데이트)
• 실습용 프로젝트 agent-gov-demo

Step 1. 그룹에서 AI 감사 이벤트 저장 기능을 활성화합니다

외부 연결 에이전트의 세션과 도구 호출이 기록되도록 최상위 그룹을 설정합니다.

최상위 그룹 > Settings > GitLab Duo > Change configuration

1. GitLab Duo Agent Platform에서 Turn on GitLab Duo Agentic Chat, agents, and flows가 선택돼 있는지 확인합니다.

   GitLab Duo 구성 화면의 Agent Platform 설정

2. Data and privacy의 AI audit event storage에서 Store AI audit events를 선택합니다.

   AI 감사 이벤트 저장 설정

3. Allow external agents가 선택돼 있는지 확인합니다. 선택이 해제돼 있으면 외부 연결 에이전트의 세션이 기록되지 않습니다.

4. Save changes를 클릭합니다.

Step 2. 그룹 안에 실습용 프로젝트를 만듭니다

Claude Code가 작업할 agent-gov-demo 프로젝트를 Step 1에서 설정한 그룹에 추가합니다.

1. 그룹 화면에서 Create project > Create blank project를 클릭합니다.
2. Project name에 agent-gov-demo를 입력하고, Visibility Level은 Private으로 둡니다.
3. Initialize repository with a README만 선택한 채 Create project를 클릭합니다.

실습용 프로젝트 생성 화면

Step 3. GitLab CLI로 로그인하고 프로젝트를 PC로 가져옵니다

1. Homebrew로 GitLab CLI(glab)를 설치하고 버전을 확인합니다. glab이 1.129.0 이상이어야 Step 4의 glab minder 명령을 쓸 수 있습니다. 버전이 낮으면 brew upgrade glab으로 업데이트합니다.

   bash

   brew install glab
   glab --version
   

2. glab으로 GitLab.com에 로그인합니다.

   bash

   glab auth login
   

   로그인할 GitLab으로 GitLab.com을, 로그인 방식으로 Web을 선택한 뒤 브라우저에서 Authorize를 클릭합니다. Git 프로토콜은 HTTPS를 선택하고, Git을 GitLab 크리덴셜로 인증할지 묻는 질문에는 Yes를 선택합니다.

3. 로그인 상태를 확인합니다. 결과에 로그인한 GitLab.com 계정이 표시되면 됩니다.

   bash

   glab auth status
   

4. 실습용 프로젝트를 PC로 복제하고 Git 리모트를 확인합니다. <그룹 경로>는 브라우저 주소창에 표시된 실제 그룹 경로로 바꿉니다.

   bash

   glab repo clone <그룹 경로>/agent-gov-demo
   cd agent-gov-demo
   git remote -v
   

   origin이 GitLab.com 주소로 표시되면 됩니다. 이 리모트가 있어야 이 폴더에서 실행한 세션이 프로젝트에 기록됩니다.

Step 4. Claude Code 세션을 GitLab으로 보내도록 설정합니다

1. glab으로 Claude Code의 세션 전송을 설정합니다. Claude Code 사용자 설정 파일에 기록용 훅이 추가되고, 30분마다 실행되는 백그라운드 작업이 설치됩니다.

   bash

   glab minder setup --agents claude-code
   

   plain

   Installing agent session hooks...
   ✓ Hooks installed in ~/.claude/settings.json
   ✓ Fallback periodic sync installed: a launchd agent (~/Library/LaunchAgents/com.gitlab.glab-govern-audit-sync.plist).
   
   Setup complete. Run 'glab minder doctor' to verify.
   

2. 설정 상태를 점검합니다. All checks passed가 표시되면 설정이 끝난 것입니다.

   bash

   glab minder doctor
   

   plain

   ✓ glab in PATH: /opt/homebrew/bin/glab
   ✓ Authentication: authenticated with gitlab.com
   ✓ Agent session hooks: Stop and SessionEnd hooks installed
   ✓ OpenCode plugin: OpenCode sessions are not synced
   ✓ API connectivity: connected to gitlab.com
   ✓ Fallback periodic sync: installed (/opt/homebrew/bin/glab); no run recorded yet
   
   ✓ All checks passed.
   

   📝 Note

   설치한 훅은 실습 폴더뿐만 아니라 이 PC에서 실행하는 모든 Claude Code 세션에서 동작합니다. 다른 폴더에서 실행한 세션도 Git 리모트가 glab으로 로그인한 GitLab을 가리키면 그 리모트의 프로젝트로 전송됩니다.

   실습을 마친 뒤 세션 전송을 멈추려면 다음 명령을 실행합니다.

   bash

   glab minder setup --uninstall
   

   훅과 백그라운드 작업이 제거되며, 이미 GitLab으로 보낸 세션은 대시보드에 남습니다.

Step 5. GitLab 통제 전: Claude Code로 main 브랜치에 push합니다

GitLab에 정책을 적용하기 전에 Claude Code가 main 브랜치에 바로 push할 수 있는지 확인합니다.

1. 프로젝트 폴더에서 Claude Code를 Manual 모드로 실행합니다.

   bash

   claude --permission-mode default
   

   실습에 사용한 Claude Code는 권한 모드를 따로 정하지 않으면 auto 모드로 시작합니다. auto 모드에서는 사람 대신 별도의 분류 모델이 작업을 검토합니다. 기본 설정에서는 main 브랜치 push도 막지 않아 Claude Code가 승인 없이 실행합니다.

   따라서 이 실습에서는 허용 규칙에 없는 작업을 실행 전에 승인받는 Manual 모드로 실행합니다. Claude Code가 이 폴더를 신뢰할지 물으면 Yes, I trust this folder를 선택합니다.

2. Claude Code에 다음과 같이 요청합니다.

   plain

   docs/guide.md 파일을 새로 만들고 '시작하기' 절을 세 문장으로 써 줘. 그다음 커밋하고 main 브랜치에 push해 줘.
   

3. Claude Code가 파일 생성과 Git 명령 실행의 승인을 요청하면 허용합니다. 결과에 main -> main이 표시되면 main 브랜치에 push된 것입니다.

   main 브랜치에 바로 push한 Claude Code

   📝 Note

   새 프로젝트의 main 브랜치는 자동으로 보호되지만, Maintainer 이상은 push할 수 있습니다. Claude Code는 glab과 Git에 설정된 계정으로 push하기에 Owner인 실습 계정의 push가 그대로 반영됐습니다.

4. /exit로 Claude Code를 종료하고, AI 감사 이벤트 보고서에서 방금 실행한 세션을 확인합니다.

   plain

   최상위 그룹 > AI > Governance > Audit events
   

   세션 목록에서 Claude Code 세션을 선택하면 세션 정보(사용자, 시각, 프로젝트, 클라이언트 유형)와 감사 이벤트가 최신순으로 표시됩니다. 도구 호출(Tool invoked), 도구 결과 수신(Tool response received), 모델 응답 수신(Llm response received)이 각각 이벤트로 남고, 이벤트를 선택하면 세부 내용을 볼 수 있습니다.

   Audit events 탭에서 연 Claude Code 세션

Step 6. 정책: CODEOWNERS, MR 승인 규칙, 보호 브랜치를 설정합니다

main 브랜치에 누구도 push할 수 없게 설정하면 GitLab 화면에서도 main 브랜치에 바로 커밋할 수 없기에 CODEOWNERS 파일을 먼저 만듭니다.

1. CODEOWNERS로 에이전트 설정 파일의 담당자를 지정합니다.

   • 프로젝트의 리포지터리 화면에서 + > New file을 선택하고, 파일 이름에 CODEOWNERS를 입력합니다.

   • 다음 내용을 넣고 main 브랜치에 커밋합니다. <사용자 이름>은 에이전트 설정 파일 담당자의 GitLab 사용자 이름으로 바꿉니다.

     plain

     # 에이전트 설정 파일은 담당자 승인을 받아야 merge할 수 있습니다
     CLAUDE.md @<사용자 이름>
     AGENTS.md @<사용자 이름>
     AGENTS.override.md @<사용자 이름>
     .mcp.json @<사용자 이름>
     /.claude/ @<사용자 이름>
     /.codex/ @<사용자 이름>
     

   • 커밋한 파일을 열어 Syntax is valid가 표시되는지 확인합니다.

     문법 검사를 통과한 CODEOWNERS 파일

2. MR 승인 규칙과 승인 설정을 변경합니다.

   보호 브랜치는 누가 push하고 merge할 수 있는지를 정하지만, 모든 MR에 승인을 요구하지는 않습니다. 따라서 MR 작성자가 아닌 사람이 1명 이상 승인해야 merge할 수 있도록 MR 승인 규칙을 설정합니다.

   plain

   프로젝트 > Settings > Merge requests > Merge request approvals
   

   • Approval rules의 Minimum required approvals 행(Any eligible user)에서 필요한 승인 수를 1로 입력합니다.
   • Approval settings에서 다음 두 항목을 선택하고 Save changes를 클릭합니다.

     • Prevent approval by merge request creator: MR 작성자가 자기 MR을 승인하지 못하게 합니다.

     • Prevent editing approval rules in merge requests: MR에서 승인 규칙을 바꿔 필요한 승인 수를 낮추지 못하게 합니다.

       MR 승인 규칙과 승인 설정

3. main 브랜치 보호 규칙을 변경합니다.

   plain

   프로젝트 > Settings > Repository > Branch rules
   

   main 브랜치의 View details를 클릭하고 다음과 같이 설정합니다.

   • Allowed to push and merge: Edit를 클릭해 No one으로 바꿉니다. 누구도 main 브랜치에 직접 push할 수 없게 됩니다.

   • Allowed to merge: Maintainers로 둡니다.

   • Require code owner approval: 활성화합니다. CODEOWNERS에 지정한 파일을 바꾼 MR은 Code Owner가 승인해야 merge할 수 있습니다.

     main 브랜치 보호 규칙

Step 7. GitLab 통제 후: push가 거부되고 MR이 승인 대기 중인지 확인합니다

Claude Code에 문서 수정과 함께 에이전트 설정 파일인 CLAUDE.md도 새로 만들어 달라고 요청해 GitLab의 통제가 실제로 작동하는지 확인합니다.

1. Claude Code를 다시 실행하고 다음과 같이 요청합니다.

   bash

   claude --permission-mode default
   

   plain

   CLAUDE.md 파일을 새로 만들어 '커밋 메시지는 한국어로 쓴다'는 규칙을 한 줄 넣고, docs/guide.md에 '문제 해결' 절을 두 문장으로 추가해 줘. 그다음 커밋하고 main 브랜치에 바로 push해 줘.
   

2. GitLab이 push를 거부하는지 확인합니다.

   Step 6에서 GitLab 화면으로 커밋한 CODEOWNERS가 PC에 없어 첫 push는 거부될 수 있고, Claude Code가 진행 방법을 물을 수 있습니다. 이때는 main 브랜치에 그대로 push하라고 답합니다. Claude Code가 원격 변경을 반영(rebase)한 뒤 다시 push하면 GitLab이 거부하며, 출력을 펼치면(ctrl+o) 다음 메시지가 보입니다.

   plain

   remote: GitLab: You are not allowed to push code to protected branches on this project.
    ! [remote rejected] main -> main (pre-receive hook declined)
   

   rebase 후 main 브랜치에 다시 push를 시도했다가 거부당한 Claude Code

3. MR로 올리도록 요청합니다.

   plain

   MR로 올려 줘. 브랜치 이름은 docs-troubleshooting으로 해 줘.
   

4. MR을 열어 merge가 차단됐는지 확인합니다. Requires 1 approval from eligible users와 Merge blocked가 표시되면 통제가 제대로 작동한 것입니다.

   승인을 기다리는 MR

   Claude Code는 glab과 Git에 설정된 GitLab 계정으로 MR을 만들기 때문에 GitLab은 그 계정을 MR 작성자로 기록합니다. Step 6에서 MR 작성자의 승인을 차단했기에 해당 GitLab 계정으로는 이 MR을 승인할 수 없습니다.

   📝 Note

   이 실습처럼 Code Owner가 MR 작성자 자신이면 Code Owner 승인은 Optional로 표시되고 merge를 막지 않습니다. 에이전트 설정 파일 변경에 Code Owner 승인을 강제하려면 MR 작성자가 아닌 다른 사용자나 그룹을 Code Owner로 지정합니다.

Step 8. 검토: 대시보드와 감사 이벤트로 기록을 확인합니다

1. AI Governance 대시보드에서 외부 연결 에이전트의 활동을 확인합니다.

   plain

   최상위 그룹 > AI > Governance > Dashboard
   

   Show에서 Connected를 클릭하면 외부 연결 에이전트의 활동만 보입니다. 이 실습에서는 Claude Code 세션 2개와 도구 호출 16건이 기록됐습니다. Top projects by agent sessions에서는 두 세션 모두 agent-gov-demo 프로젝트에서 실행됐음을 확인할 수 있습니다.

   이 밖에도 대시보드에서는 지표별 추이와 증감, 가장 많이 사용한 에이전트, 에이전트별 사용자 수, 최근 에이전트 세션, 많이 쓴 도구와 호출 유형, 그룹에 등록된 MCP 서버를 볼 수 있습니다.

   AI Governance 대시보드

2. AI 감사 이벤트 보고서에서 main 브랜치 push를 시도한 도구 호출을 찾습니다. Audit events 탭에서 Step 7의 세션을 열면, Tool invoked 이벤트의 Tool arguments에 Claude Code가 실행한 명령이 그대로 남아 있습니다. Tool call id가 같은 Tool response received 이벤트에서는 이 호출의 결과(Outcome)와 소요 시간을 볼 수 있습니다.

   main 브랜치 push를 시도한 도구 호출(Tool invoked)

   같은 도구 호출의 결과 기록(Tool response received)

   ⚠️ Warning

   Outcome이 success여도 실제 작업은 실패했을 수 있습니다. 이 실습에서도 GitLab이 push를 거부했지만, 이 호출의 Outcome은 success로 기록됐습니다. Claude Code가 git push의 출력을 tail로 넘겨 마지막 몇 줄만 보는 명령을 실행했기 때문입니다. 이런 명령은 마지막에 실행된 tail만 성공해도 전체가 성공으로 처리됩니다. 성공으로 처리된 호출은 출력도 전송되지 않아 거부 메시지가 남지 않습니다. 따라서 기록을 검토할 때는 실제로 실행한 명령도 함께 확인합니다.

3. 프로젝트 감사 이벤트에서 정책 변경 이력을 확인합니다. 승인 규칙과 보호 브랜치 설정을 누가 언제 바꿨는지 볼 수 있습니다.

   plain

   프로젝트 > Secure > Audit events
   

   프로젝트 감사 이벤트에 남은 정책 변경 이력

에이전트 거버넌스를 구축할 때 무엇을 유의해야 할까요?

앞선 실습에서는 에이전트 거버넌스의 네 단계를 프로젝트 하나에 구축했습니다. 그러나 이를 조직 전체로 확대하면 관리해야 할 에이전트와 도구, 승인 요청과 기록이 크게 늘어나죠.

2026년 들어 미국 국립표준기술연구소(NIST), 미국·영국 등 5개국 사이버보안 기관, 싱가포르와 우리나라 정부 기관이 에이전트 보안과 거버넌스 지침, 원칙을 잇따라 내놓았는데요. 이들의 공통 권고를 바탕으로 조직에 에이전트 거버넌스를 구축할 때 유의해야 할 네 가지 사항을 소개합니다.

에이전트에게 전용 계정을 주고 작업을 맡긴 사람까지 추적합니다

기록만 보고도 어떤 작업을 에이전트가 했는지, 그 작업을 누가 맡겼는지 알 수 있어야 합니다. 특히 에이전트가 사람의 계정을 그대로 쓰면, 문제가 생겼을 때 사람이 한 작업인지 에이전트가 한 작업인지 구분하기 어려운데요. NIST는 에이전트에게 사람과 분리된 계정과 자격 증명을 주고, 에이전트의 작업마다 그 작업을 시작한 사람이나 조직을 추적할 수 있게 하라고 제안하죠. 미국 사이버보안·인프라보안청(CISA) 등 5개국 6개 기관이 발표한 공동 지침 “Careful adoption of agentic AI services”도 에이전트마다 고유한 키나 인증서를 주라고 권고합니다.

정책은 지침 파일이 아니라 도구 설정과 플랫폼 기능으로 강제합니다

정책에서 금지한 작업은 에이전트 도구의 관리 설정이나 GitLab 보호 브랜치처럼 에이전트의 판단과 상관없이 작동하는 장치로 막아야 합니다. CLAUDE.md나 AGENTS.md 같은 지침 파일은 에이전트가 읽고 참고할 뿐, 이를 따르지 않아도 막을 장치가 없는데요. NIST는 에이전트가 무엇을 시도할지 정하는 로직과 무엇이 허용되는지 정하는 시스템을 구조적으로 분리해야 한다며, 가드레일만으로는 불충분하다고 지적합니다. 싱가포르 정보통신미디어개발청(IMDA)도 위험도가 높은 작업에는 프롬프트 수준의 지시보다 결정론적인 규칙 기반 통제를 권장하고요.

위험도가 높은 작업은 사람의 승인을 받도록 합니다

되돌리기 어렵거나 영향 범위가 큰 작업은 반드시 사람의 승인을 받고, 그 밖의 작업에서는 승인 요청을 줄여야 합니다. NIST는 위험 기준에 따라 사람의 검토를 요청하되, 승인 요청이 너무 잦아 습관적으로 승인하게 되는 ‘승인 피로’를 고려하라고 제언하죠. 과학기술정보통신부와 한국인터넷진흥원(KISA)이 2026년 11월 발간한 “에이전틱 AI 제로트러스트 안내서”도 되돌릴 수 없는 행위는 실행 직전에 사람이 명시적으로 승인하게 하고, 응급 대응처럼 승인을 기다릴 수 없는 행위는 사람이 미리 승인해 둔 범위 안에서 자동 실행하도록 안내합니다.

에이전트 기록은 에이전트와 분리해 보관하고 시스템 기록과 대조합니다

에이전트가 자신의 기록을 수정하거나 지울 수 없어야 하고, 기록에 남은 결과가 실제로 일어난 일과 같은지도 확인할 수 있어야 합니다. NIST는 어떤 에이전트가 누구에게서 어떤 작업을 위임받아 실제로 무엇을 했는지를, 에이전트와 독립된 로그 인프라에 변조를 발견할 수 있는 형태로 남기라고 제안하죠. 5개국 6개 기관의 공동 지침 “Careful adoption of agentic AI services”도 프롬프트와 도구 호출을 포함한 에이전트의 모든 작업을 모니터링하고, 서로 독립된 여러 모니터링 시스템으로 에이전트가 보고한 내용과 시스템 로그를 교차 검증하라고 권고합니다.

맺음말

지금까지 에이전트 거버넌스의 개념과 GitLab AI Governance의 기록 범위, GitLab과 Claude Code로 에이전트 거버넌스를 구축하는 방법, 조직에 구축할 때 유의할 점을 살펴봤습니다. 글 전체 내용을 정리하면 다음과 같습니다.

1. 에이전트 거버넌스는 에이전트가 할 수 있는 일을 규칙으로 정해 시스템으로 지키게 하는 체계로, 정책·통제·기록·검토 네 단계를 반복합니다. PC나 CI 러너의 작업은 Claude Code 관리 설정과 Codex requirements.toml로, 에이전트 설정 변경과 코드 반영은 GitLab의 CODEOWNERS와 보호 브랜치, MR 승인 규칙·승인 설정으로 관리합니다. 에이전트 도구의 이벤트는 OTel 컬렉터를 거쳐 조직의 로그 시스템으로 보내고, 에이전트 세션과 승인·설정 변경 이력은 GitLab에 남깁니다.
2. GitLab AI Governance는 glab이 보낸 외부 연결 에이전트의 세션을 대시보드와 AI 감사 이벤트 보고서에 모아 보여 주지만, PC에서 실행하는 명령을 통제하지는 않습니다. Claude Code 기준으로 프롬프트와 명령은 GitLab에 전송되고, 도구 출력과 응답 본문은 전송되지 않습니다.
3. 실습에서는 정책을 설정한 뒤 Claude Code의 main 브랜치 push가 거부되고 MR이 승인을 기다렸으며, 이 과정이 세션과 명령, 정책 변경 이력으로 남았습니다. 다만 거부된 push의 Outcome이 success로 기록된 것처럼 기록을 검토할 때는 실제로 실행한 명령도 확인해야 합니다.
4. 국내외 지침에 따르면, 조직에 구축할 때는 에이전트에게 전용 계정을 주고 작업을 맡긴 사람까지 추적하며, 정책은 지침 파일이 아니라 도구 설정과 플랫폼 기능으로 강제합니다. 되돌리기 어렵거나 영향 범위가 큰 작업은 사람의 승인을 받되 그 밖의 작업은 승인 요청을 줄이고, 에이전트 기록은 에이전트와 분리해 보관하며 시스템 기록과 대조합니다.