실패한 CI 작업은 좋은 이슈가 갖춰야 할 모든 것을 이미 알고 있습니다: 어떤 테스트가 깨졌는지, 어떤 커밋에서 발생했는지, 어떤 작업에서 발생했는지, 그리고 로그로 연결되는 링크까지 말이죠. 문제는 누군가가 빨간색 X 표시를 읽고, 세부 정보를 수동으로 트래커에 복사하고, 담당자를 지정하지 않는 한 이 정보가 파이프라인 로그 속에서 사라져 버린다는 점입니다. 그 '누군가'는 보통 잊어버리기 마련이며, 그 결과 플래키(flake) 이슈는 다음 주에 갑작스럽게 다시 나타납니다.

해결책은 파이프라인이 직접 이슈를 생성하도록 하는 것입니다. radial CLI를 사용하면 단 한 줄의 명령어로 가능합니다: radial create 명령어를 사용하고, --json 플래그를 붙여 스크립트가 방금 생성한 이슈의 식별자(identifier)를 다시 읽을 수 있도록 합니다. 브라우저도, 대시보드도, 개입하는 사람도 필요 없습니다. 또한 모든 자동화 자격 증명(credential)은 자유롭게 동작하는 에이전트이므로, 이슈를 생성하는 CI 작업에 대한 별도의 시트(seat) 비용도 발생하지 않습니다.

단 하나의 명령어

전체 과정은 다음과 같습니다. 작업이 실패하면 실패 내용을 제목으로 하는 이슈를 생성하고, 적절한 팀과 우선순위 태그를 지정한 뒤, 반환된 식별자를 캡처합니다:

# 실패 시 실행되는 CI 작업 내에서 실행. RADIAL_API_KEY는 시크릿(secret)으로 저장된 범위 제한 키(scoped key)입니다.
issue=$(radial create "CI failed on ${CI_COMMIT_SHORT_SHA}: ${FAILED_JOB}" \
  --team ENG \
...

--json 플래그는 이 스크립트를 자동화 가능하게 만드는 핵심 요소입니다. 모든 radial 명령어는 이 플래그를 지원하며, create 명령어의 경우 생성된 이슈를 단일 JSON 객체로 출력합니다. 거의 항상 필요하게 될 필드는 RAD-412와 같이 사람이 읽을 수 있는 식별자인 .id입니다. 이를 통해 파이프라인이 식별자를 출력하거나, 채팅창에 게시하거나, 다음 단계로 전달할 수 있습니다. 이슈로 바로 연결되는 링크가 필요하다면 .url이 있으며, 생성된 내용을 확인하고 싶다면 .status, .priority, .team 필드도 사용할 수 있습니다. 이들은 임의로 만들어낸 것이 아니라 응답에 포함된 실제 필드입니다. CLI는 어디서나 동일한 가독성 있는 형태를 유지하므로, 가공되지 않은 UUID 대신 RAD-412나 ENG와 같은 값을 돌려받게 됩니다.

왜 REST API가 아닌 CLI인가

curl을 사용하여 REST API를 대상으로 이 작업을 수행하는 것도 당연히 가능하며, 일부 파이프라인에서는 그것이 올바른 선택일 수 있습니다. 하지만 CLI를 사용하면 CI 내부에서 중요한 세 가지 이점을 얻을 수 있습니다:

• 단일 바이너리, 요청 파이프라인 구축 불필요 (One binary, no request plumbing). npm i -g radial.build 또는 brew install BrainGridAI/radial/radial을 실행하면 바로 명령어를 사용할 수 있습니다. Bash에서 헤더(headers), JSON 바디(JSON bodies), 에러 핸들링(error handling)을 직접 구현할 필요가 없습니다.
• 읽기 쉬운 입력, 읽기 쉬운 출력 (Human-readable in, human-readable out). 먼저 조회해야 하는 내부 ID 대신 --team ENG나 --priority high와 같은 값을 전달합니다. 응답에는 RAD-412와 같은 상태 이름이 포함되어 돌아오므로, 출력되는 식별자가 사람이 바로 인식할 수 있는 식별자가 됩니다.
• 모든 명령에 적용되는 --json 옵션. create 명령을 스크립트로 작성 가능하게 만드는 것과 동일한 플래그가 list, show, search, close 명령에도 적용되므로 CLI가 조합 가능(composes)해집니다. 정리 작업(cleanup job)에서 radial search "CI failed" --json을 실행하여 어제의 불안정한 테스트(flakes)를 찾고, 재실행으로 이미 해결된 항목들은 radial close로 닫을 수 있습니다.

이 CLI는 동일한 REST 인터페이스를 감싸는 얇고 정직한 래퍼(wrapper)입니다. 이미 특정 언어 런타임(language runtime)에 깊게 몰입해 있어 의존성을 추가하는 것이 번거롭다면 curl을 사용하세요. 하지만 쉘 스크립트(shell script)에서 가장 짧고 정확한 한 줄을 원한다면 CLI를 선택하세요.

자격 증명: 시크릿으로 저장되는 범위 제한 키 (a scoped key, stored as a secret)

CI는 비대화형(non-interactive)이므로

그리고 해당 키는 워크스페이스 내에서 자체적인 에이전트 정체성 (agent identity)을 제공하며, 이는 유료 시트 (billed seat)로 계산되지 않습니다. 귀하의 CI 봇은 50달러짜리 사용자가 아닙니다. 팀의 인간들이 시트이며, 파이프라인은 API의 무료 클라이언트입니다. 제품 어디에도 에이전트당 요금이 부과되거나 AI 크레딧 미터 (AI credit meter)가 존재하지 않는데, 이는 실제적으로 'Plain Software Pledge(정직한 소프트웨어 약속)'를 따르는 것입니다. 즉, Radial이 코파일럿 (copilot)을 출시하거나, 사용량을 측정하거나, 요청하지 않은 AI에 대해 비용을 청구하는 날, 귀하의 구독은 무료가 됩니다.

파이프라인에 연결하기

이 패턴은 제공자 중립적 (provider-agnostic)입니다. 왜냐하면 CI가 이미 설정해 둔 환경 변수 (environment variables)를 읽는 단순한 셸 명령 (shell command)이기 때문입니다. GitLab CI에서는 after_script 또는 when: on_failure 조건의 작업이며, GitHub Actions에서는 if: failure() 조건의 단계 (step)이고, Jenkins 파이프라인에서는 post { failure { ... } } 블록입니다. 모든 경우에 그 형태는 동일합니다:

1. 작업 (job)이 실패합니다.
2. 실패 후크 (failure hook)가 CI 환경 변수에서 가져온 커밋 (commit), 브랜치 (branch), 작업 URL을 사용하여 radial create를 실행합니다.
3. --json이 새로운 이슈 (issue)를 반환합니다. 귀하는 .id와 .url을 캡처하여 출력하거나 게시합니다.

create 명령은 사용자가 직접 그렇게 만들지 않는 한 멱등성 (idempotent)을 보장하지 않으므로, 단순하게 설정하면 불안정한 작업 (flaky job)이 실패할 때마다 새로운 이슈를 생성하게 됩니다. 만약 이것이 너무 번거롭다면, 생성하기 전에 radial search --json 가드 (guard)를 추가하세요. 동일한 제목을 가진 열린 이슈가 있는지 확인하고, 이미 존재하는 경우가 아닐 때만 radial create를 실행하는 방식입니다. 모든 명령어가 --json을 지원하기 때문에 CLI는 정밀하게 조합 (compose)될 수 있습니다.

FAQ

CI 파이프라인에서 자동으로 이슈를 생성하려면 어떻게 하나요?

파이프라인의 실패 후크 (GitLab when: on_failure, GitHub Actions if: failure(), Jenkins post { failure }) 내에서 radial create를 실행하세요. CI 환경 변수로부터 생성한 제목, 팀, 우선순위, 설명을 전달하고, 파이프라인이 생성된 이슈의 식별자를 다시 읽을 수 있도록 --json을 추가하세요. CI 시크릿 (secret)으로 저장된 범위 제한 API 키 (rk_)로 인증하세요. 이것이 통합의 전부입니다. 플러그인도, 웹훅 서버 (webhook server)도 필요 없이, 그저 후크 내의 CLI 명령 하나면 충분합니다.

스크립트에서 생성된 새 이슈의 ID를 어떻게 다시 가져오나요?

radial create에 --json을 추가하세요. 생성된 이슈를 JSON 객체로 출력하며, 사람이 읽을 수 있는 식별자(identifier)는 .id 필드에 들어 있습니다 (예: RAD-412). jq -r '.id'를 통해 파이프(pipe)로 연결하면 식별자만 캡처할 수 있고, .url을 읽으면 이슈로 바로 연결되는 링크를 얻을 수 있습니다. CLI가 반환하는 모든 필드는 설계 단계부터 사람이 읽을 수 있도록 만들어졌으므로, UUID 대신 RAD-412나 ENG와 같은 값을 받게 됩니다.

CI 봇이 이슈를 등록하면 시트(seat) 비용이 발생하나요?

아니요. 해당 작업을 위해 생성한 API 키는 에이전트 멤버 (agent member)를 프로비저닝하며, 에이전트 멤버는 과금 대상 시트 (billed seats)에 포함되지 않습니다. 워크스페이스의 실제 사용자에 대해서는 **사용자당 연간 50달러(매년 청구)**의 고정 비용을 지불하며, CI 봇이나 트리아지 에이전트 (triage agent), 혹은 그들의 대규모 군단을 추가하더라도 그 숫자는 변하지 않습니다. 에이전트는 무료입니다.

불안정한 작업 (flaky job)이 실패할 때마다 중복 이슈가 생성되는 것을 어떻게 방지하나요?

생성(create) 명령 전에 검색(search) 과정을 통해 방어하세요. 먼저 radial search "<실패한 제목>" --json을 실행하고, 열려 있는 일치 항목이 없을 때만 radial create를 호출하십시오. 모든 radial 명령은 --json을 지원하므로, 검색 결과는 기계 판독이 가능하며 셸 조건문 (shell condition)에서 테스트하기 쉽습니다. 임포트 (Import)는 단일 실행이며 create는 자동으로 중복 제거 (deduplication)를 해주지 않으므로, 이 방어 기제는 트래커가 동일한 불안정한 작업의 복사본으로 가득 차는 것을 막는 방법입니다.

셸 스크립트 대신 코딩 에이전트 (coding agent)가 이 작업을 수행할 수 있나요?

네. Claude Code와 같은 대화형 에이전트가 이미 MCP 서버를 통해 연결되어 있다면, 실패하는 작업을 감지했을 때 CLI 없이도 직접 create_issue를 호출할 수 있습니다. CLI 경로는 브라우저를 사용하는 사람이 없는 헤드리스 (headless) 환경에서 실행되는 파이프라인과 같은 비대화형 (non-interactive) 케이스를 위한 것입니다. 동일한 트래커, 동일한 무료 에이전트 신원을 사용하며, 두 가지 진입 방식이 존재합니다.

요약 버전

레드 파이프라인(red pipeline)은 스스로 이슈를 생성해야 합니다. CLI를 설치하고, 범위가 지정된(scoped) write 키를 하나 발급(mint)한 뒤, 실패 후크(failure hook)에서 radial create ... --json을 실행하세요. 그런 다음 .id를 다시 읽어와 방금 생성한 이슈를 연결하면 됩니다. CI 봇은 프리 에이전트(free agent)이며, 반환되는 식별자는 사람이 인식할 수 있는 것이고, 이 과정에서 비용(meter)이 발생하지 않습니다.

전체 CLI 및 API 인터페이스는 developers 페이지에서 확인하거나, 범위가 지정된 API 키(scoped API keys)를 통해 각 자동화 프로세스에 정확히 필요한 권한만 부여하는 방법을 읽어보세요.

원문은 Radial 블로그에 게시되었습니다.