Fix CI/CD Pipeline Flow는 GitLab CI/CD 파이프라인의 문제를 진단하고 수정안을 제안합니다. 이 플로는 실패를 진단하기 위해 다음을 살펴봅니다.

• 오류 메시지, 실패한 job의 출력, 종료 코드를 포함한 파이프라인 로그.
• 실패의 원인이 되었을 수 있는 머지 리퀘스트 변경 사항.
• 구문, 린팅, import 오류를 찾기 위한 리포지터리 콘텐츠.
• 명령 실패, 실행 파일 누락, 권한 문제를 포함한 스크립트 오류.

플로가 수정을 적용하는 방식은 파이프라인 컨텍스트에 따라 다릅니다.

• 파이프라인이 머지 리퀘스트와 연결되어 있으면 플로가 소스 브랜치에 인라인 코드 제안을 적용합니다. 제안은 머지 리퀘스트에서 바로 검토하고 적용할 수 있습니다.
  • 수정에 현재 머지 리퀘스트 diff 바깥의 파일 변경이 필요하면 플로가 대신 새 머지 리퀘스트를 생성합니다.
• 파이프라인이 머지 리퀘스트와 연결되어 있지 않으면 플로가 수정 내용을 담은 새 머지 리퀘스트를 생성합니다.

경우에 따라 플로는 수정을 시도하는 대신 실패 내용과 이후 조치를 설명하는 댓글을 남깁니다. 파이프라인이 머지 리퀘스트와 연결된 경우 다음과 같은 상황에서 그렇습니다.

• 신뢰할 수 있는 수정안을 판단할 만한 컨텍스트가 부족한 경우.
• 실패가 보안에 민감해 사람이 검토해야 하는 경우.
• 실패 유형이 플로가 조치할 수 있는 범위가 아닌 경우.

세션이 시작되고 완료되면 플로가 세션 링크와 함께 시스템 노트를 머지 리퀘스트에 남깁니다. 이 플로는 GitLab UI에서만 사용할 수 있습니다.

GitLab Duo Agent Platform을 사용하면서 실패한 파이프라인을 자동으로 수정하려는 경우 이 플로를 권장합니다. 이는 단일 job 실패를 해결하는 GitLab Duo Chat 기능인 근본 원인 분석과는 별개의 기능입니다.

사전 요구 사항#

• GitLab Duo Agent Platform의 사전 요구 사항을 충족합니다.
• 최상위 그룹에서 Allow foundational flows와 Fix CI/CD Pipeline을 켭니다.
• 프로젝트의 Developer, Maintainer 또는 Owner 권한이 있어야 합니다.
• 실패한 파이프라인이 있어야 합니다.
• 서비스 계정을 허용하도록 푸시 규칙을 구성합니다.
• 직접 러너를 구성하거나 프로젝트에 GitLab 호스티드 러너를 켭니다.
• 권장 사항. 플로가 프로젝트의 툴체인과 의존성에 접근할 수 있도록 에이전트 구성 파일을 만듭니다.

머지 리퀘스트에서 파이프라인 수정#

머지 리퀘스트에서 CI/CD 파이프라인을 수정하려면 다음 단계를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.

2. 왼쪽 사이드바에서 Code > Merge requests를 선택하고 머지 리퀘스트를 엽니다.

3. 다음 방법 중 하나로 파이프라인을 수정합니다.

   • Overview 탭을 선택한 다음 실패한 파이프라인 아래에서 Fix pipeline with Duo를 선택합니다.
   • Pipelines 탭을 선택한 다음 가장 오른쪽 칼럼에서 Fix pipeline with Duo([tanuki-ai])를 선택합니다.
   • GitLab Duo 사이드바에서 새 Agentic Chat 대화를 열거나 기존 대화를 엽니다. Agentic Chat에 파이프라인 수정을 요청합니다.

4. 진행 상황을 확인하려면 왼쪽 사이드바에서 AI > Sessions를 선택합니다.

   Agentic Chat을 사용 중이라면 다음 방법도 있습니다.

   • Chat 대화에서 진행 상황을 확인합니다.
   • 대화에서 View Agent Session을 선택합니다.

세션이 완료되면 플로가 머지 리퀘스트에 코드 제안을 추가하거나, 이후 조치를 설명하는 댓글을 남깁니다.

다른 CI/CD 파이프라인 수정#

머지 리퀘스트와 연결되지 않은 CI/CD 파이프라인을 수정하려면 다음 단계를 따릅니다.

1. Build > Pipelines를 선택합니다.
2. 실패한 파이프라인을 선택합니다.
3. 오른쪽 상단에서 Fix pipeline with Duo를 선택합니다.
4. 진행 상황을 확인하려면 AI > Sessions를 선택합니다.

AGENTS.md로 플로 맞춤 설정#

플로는 리포지터리의 AGENTS.md 파일에서 리포지터리별 지침을 읽습니다. AGENTS.md로 다음과 같은 동작을 맞춤 설정할 수 있습니다.

• 플로가 커밋하는 변경의 커밋 메시지 형식.
• 플로가 생성하는 머지 리퀘스트의 레이블, 설명 같은 메타데이터.
• 특정 유형의 실패를 분류하고 처리하는 방식.
• 같은 유형의 실패가 반복될 때 플로가 같은 수정안을 여러 번 시도하지 않도록 처리하는 방식.

예를 들면 다음과 같습니다.

## Fix pipeline merge requests

When opening a merge request as part of the Fix Pipeline flow (the title contains [FixPipeline]),
apply labels based on the following failed pipeline scenarios:

- Pipeline failed on merge_request: apply "pipeline::tier-1". This runs the cheaper tier-1
  pipeline instead of the full default pipeline.
- Pipeline failed on the default_branch (main): apply both "pipeline::expedited" and
  "main:broken". Do not apply pipeline::tier-1 in this case.
- Pipeline failed on other branches: apply "pipeline::tier-1". Same treatment as the
  merge_request case.

마이그레이션 실패를 처리하는 예는 다음과 같습니다.

## Migration failures

If a pipeline fails because of a database migration:

- Run `bin/rails db:migrate:status` to check the current migration state before attempting
  a fix.
- Do not edit or delete past migration files.
- If the migration cannot be safely reversed, post a comment describing the issue instead
  of attempting a fix.

알려진 문제#

• AI gateway는 job 로그의 마지막 150KiB만 처리합니다. job이 많은 출력을 남기면 로그 앞부분에 있는 실패 정보를 플로가 확보하지 못할 수 있습니다. 해결 방법은 다음 섹션을 참고합니다.
• 플로가 샌드박스 런타임 환경에서 패키지 설치를 항상 확인할 수 있는 것은 아닙니다. 의존성이 없다면 기본 플로 이미지를 맞춤 설정할 수 있습니다. 기본 Docker 이미지 변경을 참고합니다.
• AGENTS.md의 리포지터리 지침은 플로 동작에 영향을 주지만 모든 경우에 반드시 지켜지는 것은 아닙니다.

문제 해결#

Fix CI/CD Pipeline Flow를 사용할 때 다음과 같은 문제가 발생할 수 있습니다.

플로가 실패의 근본 원인을 식별할 수 없음#

플로가 파이프라인 실패의 근본 원인을 찾지 못할 수 있습니다.

이 문제는 job 로그가 150KiB를 넘을 때 발생합니다. AI gateway는 마지막 150KiB만 처리하므로 로그 앞부분에 있는 실패 정보를 확보하지 못할 수 있습니다.

이 문제를 우회하려면 다음을 시도합니다.

• 디버그 로깅과 진행 표시를 없애 출력량을 줄입니다.
• 중요하지 않은 출력은 셸 리디렉션(> /dev/null)으로 돌립니다.
• 스크립트 마지막에 주요 오류 메시지를 출력하는 요약 단계를 추가합니다.
• after_script로 기본 스크립트가 끝난 뒤 진단 정보를 출력합니다.
• 출력이 많은 job을 로그가 더 간결한 작은 job으로 나눕니다.

세션을 시작하지 못함#

Fix CI/CD Pipeline Flow의 세션이 실패하고, 세션 페이지(AI > Sessions)에 Session failed to start 알림이 표시됩니다.

여기에는 실패한 파이프라인과, 이를 수정하기 위해 플로가 생성하는 워크로드 파이프라인 두 가지가 관련됩니다. 워크로드 파이프라인의 job 상태를 확인합니다.

원인과 해결 방법은 플로의 job 또는 세션이 시작되지 않는 경우를 참고합니다.

Fix pipeline with Duo 버튼이 표시되지 않음#

사전 요구 사항을 충족했는데도 Fix pipeline with Duo 버튼이 표시되지 않습니다.

이 문제는 해당 버튼이 서로 다른 세 페이지(GitLab Duo, Agent Platform, 파운데이셔널 플로)의 설정에 좌우되기 때문에 발생합니다. 상위 수준에서 설정을 켰다고 해서 하위 수준에서도 모두 켜져 있다는 보장은 없습니다.

이 문제를 해결하려면 각 요구 사항을 다시 확인합니다.

• GitLab Duo 또는 GitLab Duo Core가 켜져 있습니다.
• Agent Platform이 켜져 있습니다.
• 최상위 그룹과, GitLab Self-Managed의 경우 인스턴스에서 Allow foundational flows와 Fix CI/CD Pipeline이 켜져 있습니다.

피드백 제공#

팀은 Fix CI/CD Pipeline Flow를 지속적으로 개선하고 있습니다. 문제를 신고하거나 개선을 제안하려면 피드백 이슈 601991에 의견을 남겨 주시기 바랍니다.