> For the complete documentation index, see [llms.txt](https://genos-docs.gitbook.io/default/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://genos-docs.gitbook.io/default/v1.9.4/admin-management/settings/bulk-control.md).

# 일괄 제어

일괄 제어는 **오랫동안 호출되지 않은 워크플로우를 찾아 한 번에 배포 중지**하는 기능입니다. 워크플로우가 배포된 채로 방치되면 GPU·메모리 같은 자원을 계속 점유하므로, 주기적으로 미사용 워크플로우를 정리하는 용도로 사용합니다.

관리자는 **관리 > 일괄 제어**(`/admin/bulk-control`) 메뉴에서 전체 워크플로우를, 일반 사용자는 **마이페이지 > 일괄 제어** 탭에서 본인이 만든 워크플로우를 대상으로 사용합니다.

<figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2Fgit-blob-321e699041e31d72ba10cb562425bf8847f73b87%2Fbulkctl_01_bulk_control_list.png?alt=media" alt=""><figcaption><p>관리 > 일괄 제어 화면</p></figcaption></figure>

### 주요 개념

| 개념        | 설명                                                                                    |
| --------- | ------------------------------------------------------------------------------------- |
| 미사용 워크플로우 | 선택한 기간 동안 한 번도 호출되지 않은, 현재 배포(온라인) 상태의 워크플로우입니다.                                      |
| 미사용 기간    | 미사용 여부를 판정하는 기간입니다. 제한 없음 / 최근 7·14·30일 / 직접 선택(최대 90일) 중에서 고릅니다.                     |
| 연결된 리소스   | 그 워크플로우를 쓰고 있는 채팅 앱·보고서 생성·데이터 분석·서비스 라우터·가드레일·확장 서비스입니다. 목록의 '연결된 리소스' 버튼에서 확인합니다.   |
| 동반 해제     | 워크플로우를 중지할 때 **함께 내려가거나 연결이 끊기는** 리소스입니다. 채팅 앱·가드레일·서비스 라우터·확장 서비스(AI 회의록) 4종이 대상입니다. |
| 신청(배치)    | 한 번에 선택한 워크플로우 여러 건을 묶은 단위입니다. 결재·취소·실행이 모두 이 단위로 움직입니다.                              |
| 결재        | 신청 건을 승인·반려하는 절차입니다. **운영 > 승인** 메뉴에서 처리합니다.                                          |
| 자동 승인     | 관리 화면에서 관리자가 신청한 건은 결재 없이 바로 실행됩니다.                                                   |

### 사용 권한과 진입 경로

| 화면            | 경로                     | 사용할 수 있는 사람         | 보이는 범위                             |
| ------------- | ---------------------- | ------------------- | ---------------------------------- |
| 관리 > 일괄 제어    | `/admin/bulk-control`  | 슈퍼 관리자              | 현재 워크스페이스에서 **수정 권한이 있는** 모든 워크플로우 |
| 마이페이지 > 일괄 제어 | `/my-page` 의 '일괄 제어' 탭 | 모든 사용자              | **본인이 만든** 워크플로우                   |
| 운영 > 승인       | `/approval`            | 일괄 제어 권한(읽기/쓰기) 보유자 | 결재 대기 중인 일괄 제어 신청                  |

* 관리 메뉴는 슈퍼 관리자에게만 보입니다. 워크스페이스 관리자(owner·admin)도 일반 사용자와 같이 마이페이지 경로를 사용합니다.
* 어느 경로든 **대상 워크플로우를 수정할 권한**과 **함께 내려갈 연결 리소스를 해제할 권한**이 모두 있어야 신청할 수 있습니다.
* 목록은 현재 선택한 워크스페이스 기준으로 표시됩니다.

### 중지 대상 찾기

화면에 들어오면 기본값인 **최근 30일** 기준으로 후보가 조회됩니다. 목록에는 아래 조건을 **모두** 만족하는 워크플로우만 나옵니다.

1. 현재 배포(온라인) 상태다.
2. 판정 기간이 시작되기 **전에** 배포됐다. — 기간 도중에 새로 배포한 워크플로우는 "그 기간 내내 안 쓰였다"가 성립하지 않으므로 제외됩니다. 기준은 가장 최근 배포 시각이라, 재배포하면 초기화됩니다.
3. 그 기간 동안 호출 건수가 0건이다.

필터 위 안내 문구가 현재 어떤 기준으로 조회 중인지 알려 줍니다(예: "배포한 지 30일이 지났지만 그동안 호출되지 않은 온라인 워크플로우만 표시됩니다.").

#### 필터

<figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2Fgit-blob-2a699a621ad76fbbc40817f2bfa67aded333e463%2Fbulkctl_02_unused_period_filter.png?alt=media" alt=""><figcaption><p>미사용 기간 필터</p></figcaption></figure>

| 필터     | 설명                                                        |
| ------ | --------------------------------------------------------- |
| 관리 그룹  | 워크플로우가 속한 관리 그룹으로 좁힙니다. 여러 개 선택할 수 있고, 처음에는 전체가 선택돼 있습니다. |
| 생성자    | 워크플로우를 만든 사람으로 좁힙니다. (마이페이지 탭에서는 본인 것만 보이므로 표시되지 않습니다.)   |
| 미사용 기간 | **제한 없음** / 최근 7일 / 최근 14일 / 최근 30일 / **직접 선택** 중에서 고릅니다. |

* **제한 없음**을 고르면 사용 여부를 따지지 않고 **배포 중인 워크플로우 전체**가 표시됩니다. 이때 안내 문구도 "연결 상태 온라인인 모든 워크플로우가 표시됩니다."로 바뀝니다.
* **직접 선택**은 시작일·종료일을 직접 지정합니다. 최대 90일까지 조회할 수 있습니다.
* 기본값(최근 30일)에서 필터를 바꾸면 **초기화** 버튼이 나타납니다. 누르면 기본 상태로 되돌아갑니다.

#### 목록에서 볼 수 있는 정보

| 컬럼                 | 설명                                              |
| ------------------ | ----------------------------------------------- |
| ID / 버전 ID         | 워크플로우 ID와 현재 배포된 버전(리비전) ID입니다.                 |
| 워크플로우 이름           | 행을 더블클릭하면 워크플로우 상세 화면으로 이동합니다.                  |
| 연결 상태              | 배포 상태입니다. 목록에는 '온라인'만 표시됩니다.                    |
| 배포 상태              | 이미 중지 신청이 올라가 결재를 기다리는 행에 **승인 대기 중** 배지가 붙습니다. |
| 관리 그룹 / 생성자 / 생성일시 | 워크플로우 소속과 만든 사람입니다.                             |
| 최근 호출일시            | 마지막으로 호출된 시각입니다. 기록이 없으면 `-` 로 표시됩니다.           |
| 연결된 리소스            | 그 워크플로우를 사용 중인 리소스 건수입니다. 버튼을 눌러 상세를 확인합니다.     |

정렬은 **워크플로우 이름 · 생성일시 · 최근 호출일시** 3개 컬럼에서 가능하며, 헤더를 누를 때마다 오름차순 → 내림차순 → 정렬 없음 순으로 바뀝니다. 기본은 생성일시 최신순입니다.

> **최근 호출일시 참고** — 이 값은 게이트웨이를 거친 호출에서 기록됩니다. 구 사양의 MCP 직접 호출처럼 게이트웨이를 우회하는 경로는 반영되지 않을 수 있습니다. 다만 **미사용 판정 자체는 이 값이 아니라 실시간 호출 집계로 하므로** 판정 결과에는 영향이 없습니다.

#### 목록이 비어 있을 때

| 상황               | 화면                                                                             |
| ---------------- | ------------------------------------------------------------------------------ |
| 조건에 맞는 워크플로우가 없음 | "미사용 워크플로우가 없습니다." (미사용 기간이 '제한 없음'이면 "워크플로우가 없습니다.")                          |
| 필터를 걸어 0건이 됨     | 위 문구 + "필터를 조정해 보세요." 와 초기화 버튼                                                 |
| 이용 로그 조회 실패      | **"이용 로그를 조회하지 못했습니다."** — 모니터링 조회에 실패해 미사용 여부를 판정할 수 없는 상태입니다. 잠시 후 다시 시도합니다. |
| 이용 로그 수집 중단 의심   | **"이용 로그 수집이 중단된 것으로 보입니다."** — 선택한 기간 동안 전체 워크플로우 호출이 0건이라 판정을 신뢰할 수 없습니다.    |

뒤의 두 경우는 **후보가 0건인 것이 아니라 판정을 할 수 없는 상태**이므로, 목록을 비우고 안내를 띄웁니다. 이 상태에서는 중지를 신청하지 않는 것이 안전합니다.

### 연결된 리소스 미리 확인하기

중지하면 어떤 서비스가 영향을 받는지 신청 전에 확인할 수 있습니다. 목록의 **연결된 리소스 (N)** 버튼을 누르면 오른쪽에 패널이 열립니다.

<figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2Fgit-blob-7275da16f0ff1bb3d213bc11b64086b628cfaf57%2Fbulkctl_03_connected_resources_panel.png?alt=media" alt=""><figcaption><p>연결된 리소스 패널</p></figcaption></figure>

패널에는 채팅 앱 · 보고서 생성 · 데이터 분석 · 서비스 라우터 · 가드레일 · 확장 서비스가 유형별로 묶여 나오고, 각 항목 이름을 누르면 해당 리소스 화면이 새 탭으로 열립니다. 상단에는 **"워크플로우 배포를 중지하면 아래 리소스도 함께 내려갑니다."** 안내가 표시됩니다.

> 이 안내는 카나리가 진행 중인 워크플로우에는 표시되지 않습니다. 그 경우 중지 자체가 막혀 있어 "함께 내려간다"는 설명이 성립하지 않기 때문입니다.

함께 내려가는 대상(동반 해제)은 아래 4종입니다. 보고서 생성·데이터 분석은 패널에 건수가 보이더라도 동반 해제 대상이 아닙니다.

| 유형             | 중지 시 동작                 |
| -------------- | ----------------------- |
| 채팅 앱           | 배포 중지됩니다.               |
| 가드레일           | 워크플로우에 걸린 필터 연결이 해제됩니다. |
| 서비스 라우터        | 라우터의 타깃 목록에서 제거됩니다.     |
| 확장 서비스(AI 회의록) | 해당 설정이 꺼집니다.            |

### 배포 중지 신청하기

1. 중지할 워크플로우의 체크박스를 선택합니다. 상단에 **"N개 중 M개 선택됨"** 이 표시되고 **배포 중지** 버튼이 활성화됩니다.

   <figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2Fgit-blob-40942a53820ded685423ab7a0baec66b483dcd2c%2Fbulkctl_04_select_targets.png?alt=media" alt=""><figcaption><p>대상 선택</p></figcaption></figure>
2. **배포 중지** 버튼을 누르면 확인 창이 뜹니다. 연결된 리소스도 함께 정리된다는 안내를 확인하고 **확인**을 누릅니다.

   <figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2Fgit-blob-0a8d6f8de4dd7d6be68c9ccf1fd007c9b453f7f9%2Fbulkctl_05_stop_confirm_modal.png?alt=media" alt=""><figcaption><p>배포 중지 확인</p></figcaption></figure>
3. 신청 결과에 따라 안내 메시지가 다르게 표시됩니다.

| 상황              | 메시지               | 이후 흐름                        |
| --------------- | ----------------- | ---------------------------- |
| 관리 화면에서 관리자가 신청 | "배포 중지가 시작되었습니다." | 결재 없이 곧바로 실행됩니다.             |
| 마이페이지에서 신청      | "배포 중지가 신청되었습니다." | 결재 대기 상태가 되고, 결재자에게 알림이 갑니다. |

> **이 버튼을 누른 시점에 워크플로우가 내려가는 것은 아닙니다.** 자동 승인 건은 바로 실행 대기열에 올라가고, 결재가 필요한 건은 승인된 뒤에 실행됩니다. 마이페이지에서 올린 신청은 **신청자가 관리자여도** 결재를 거칩니다.

신청이 끝나면 선택이 해제되고 목록이 다시 조회됩니다. 방금 신청한 워크플로우는 **승인 대기 중** 배지가 붙고 다시 선택할 수 없게 됩니다.

### 선택할 수 없는 워크플로우

목록에는 지금 중지할 수 없는 워크플로우도 함께 표시됩니다. 이런 행은 체크박스가 비활성화되며, 체크박스에 마우스를 올리면 사유가 표시됩니다.

| 사유               | 안내 문구                                                 | 해소 방법                              |
| ---------------- | ----------------------------------------------------- | ---------------------------------- |
| 이미 신청됨           | "배포 중지 승인 대기 중으로 선택할 수 없습니다."                         | 결재가 처리되거나 신청을 취소하면 풀립니다.           |
| 카나리 진행 중         | "카나리가 진행 중입니다. 전면 전환 또는 원복 후 중지할 수 있습니다."             | 카나리를 먼저 정리합니다.                     |
| 서비스 라우터 카나리 진행 중 | "서비스 라우터 카나리가 진행 중입니다. 카나리 정리 후 중지할 수 있습니다."          | 라우터 카나리를 먼저 정리합니다.                 |
| 연결 리소스 권한 없음     | "연결된 채팅 앱/가드레일/서비스 라우터/확장 서비스(AI 회의록)를 해제할 권한이 없습니다." | 해당 리소스 권한을 가진 담당자가 신청하거나 권한을 받습니다. |
| 그 외              | "지금은 중지를 신청할 수 없는 워크플로우입니다."                          | —                                  |

> 카나리는 시스템이 자동으로 정리하지 않습니다. 전면 전환 또는 원복으로 **사용자가 먼저 정리**해야 중지할 수 있습니다.

또한 아래 워크플로우는 애초에 후보 목록에 나오지 않습니다.

* **코드 서빙 기반 워크플로우** — 워크플로우 화면에서 중지 자체가 막혀 있고, 실행이 코드 서빙 컨테이너에서 일어나 호출 관측이 항상 0건으로 잡힙니다.
* **최근 사용된 채팅 앱에 연결된 워크플로우** — 라우터 모드 채팅처럼 워크플로우 호출 기록이 0건이어도 실제로는 매일 쓰이는 경우가 있어, 채팅 사용 이력으로 한 번 더 걸러 냅니다.

### 결재 — 신청 검토하고 승인하기

마이페이지에서 올라온 신청은 **운영 > 승인** 메뉴에서 처리합니다. 일괄 제어 권한(읽기 이상)이 있는 사용자에게 결재 요청 알림이 가고, 쓰기 권한이 있으면 **검토** 버튼이 표시됩니다.

알림 토스트의 **검토** 를 눌러도 화면 이동 없이 그 자리에서 같은 모달이 열립니다.

<figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2Fgit-blob-8dd5b5c22fcb4b2ec1338365e88d648b9b4b07d6%2Fbulkctl_06_approval_review_modal.png?alt=media" alt=""><figcaption><p>결재 상세 모달</p></figcaption></figure>

모달은 세 부분으로 나뉩니다.

| 영역       | 내용                                            |
| -------- | --------------------------------------------- |
| 신청 내용    | 신청자·신청일시, 결재 유형(배포), 상태(중지), 상세 유형(워크플로우), 대상 |
| 신청 내용 상세 | 대상 워크플로우 목록과 변경 전(온라인) → 변경 후(오프라인)           |
| 결재 결과    | 결재 상태(대기/승인/반려/신청 취소), 결재자·결재일시, 반려 사유        |

각 워크플로우 행 오른쪽의 화살표를 펼치면 **중지/연결 해제 예정인 연결된 리소스**가 함께 나옵니다. "워크플로우 몇 개가 꺼진다"만 보고 승인하지 않도록, 어떤 채팅 앱·가드레일·라우터가 같이 내려가는지 확인한 뒤 판단합니다.

<figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2Fgit-blob-7e4aa79adbfc0a8820d734024ea69ac752e14073%2Fbulkctl_07_approval_review_cascade.png?alt=media" alt=""><figcaption><p>동반 해제 대상 펼치기</p></figcaption></figure>

* **승인** — 확인 창을 거친 뒤 실행 대기열에 올라갑니다.
* **반려** — 사유를 입력하는 창이 뜹니다. 입력한 사유는 신청자에게 전달되고 결재 상세에도 남습니다.
* 리소스 이름을 누르면 워크플로우 상세 화면으로 이동해 내용을 직접 확인할 수 있습니다.
* 승인 목록에서 일괄 제어 행을 **더블클릭**하면 그 신청이 올라온 화면(관리 화면 또는 마이페이지 일괄 제어 탭)으로 이동합니다.

### 마이페이지에서 내 워크플로우 정리하기

마이페이지 **일괄 제어** 탭은 관리 화면과 같은 목록을 **본인이 만든 워크플로우**로만 좁혀 보여 줍니다. 필터·선택·신청 방법은 관리 화면과 같고, 생성자 필터만 없습니다.

<figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2Fgit-blob-585b907d5dfddd0685692e9f0bb2cb8902f0435a%2Fbulkctl_08_my_page_tab.png?alt=media" alt=""><figcaption><p>마이페이지 일괄 제어 탭</p></figcaption></figure>

### 신청 취소하기

승인 전이라면 신청자가 직접 철회할 수 있습니다. 승인 대기 중인 워크플로우 행에 **배포 중지 취소** 버튼이 표시되며, 확인 창에서 **확인**을 누르면 철회됩니다.

* **취소 단위는 행이 아니라 신청(배치)입니다.** 같은 신청에 묶여 있던 다른 워크플로우도 함께 취소되며, 확인 창에 이 내용이 안내됩니다.
* **신청자 본인만** 취소할 수 있습니다. 결재자는 반려로 같은 결과를 만들 수 있고, 그 경우에는 사유가 기록됩니다.
* 이미 승인·반려됐거나 실행이 시작된 뒤에는 취소할 수 없습니다.
* 취소하면 해당 워크플로우의 '승인 대기 중' 배지가 사라지고 다시 신청할 수 있게 됩니다.

### 승인 이후 — 실행 결과

승인된 신청은 순차적으로 실행됩니다. 워크플로우 1건마다 **연결된 리소스를 먼저 해제하고, 그다음 배포를 중지**합니다.

| 결과    | 의미                                                                          |
| ----- | --------------------------------------------------------------------------- |
| 완료    | 신청한 워크플로우가 모두 중지됐습니다.                                                       |
| 부분 실패 | 일부는 중지되고 일부는 실패했습니다. 실패한 건은 원래 상태로 되돌려집니다.                                  |
| 실패    | 모두 실패했습니다.                                                                  |
| 건너뜀   | 승인 후 재확인 시점에 이미 꺼져 있거나, 카나리가 시작됐거나, 해제 권한이 사라진 경우입니다. 실패가 아니라 정상 결과로 처리됩니다. |

중지 도중 오류가 나면 그 워크플로우에 대해 해제했던 연결을 되돌립니다. 되돌리기까지 실패한 경우에는 잔여물이 남을 수 있어 담당자의 확인이 필요합니다.

### 오류·예외 처리

| 발생 상황                                                 | 화면 표시                                          |
| ----------------------------------------------------- | ---------------------------------------------- |
| 일괄 제어 조회·신청 권한이 없음                                    | "관리자만 허용된 작업입니다."                              |
| 남의 워크플로우를 포함해 신청 / 워크플로우 수정 권한 없음 / 신청자가 아닌 사람이 취소 시도 | 서버가 내려준 사유 문구                                  |
| 이미 배포 중이 아닌 워크플로우를 신청                                 | 해당 워크플로우 ID와 함께 안내                             |
| 서비스 라우터 카나리가 진행 중                                     | 카나리 정리 후 다시 시도 안내                              |
| 이미 결재 처리됐거나 실행이 시작된 신청을 취소                            | 취소 불가 안내                                       |
| 이용 로그 조회 실패·수집 중단 의심                                  | 목록 상단 안내 배너 (위 [목록이 비어 있을 때](#목록이-비어-있을-때) 참고) |

### 사용자 시나리오

#### 시나리오 1 — 관리자가 분기별로 미사용 워크플로우를 정리한다

관리자가 **관리 > 일괄 제어**에 들어가 미사용 기간을 '최근 30일'로 둔 채 목록을 확인합니다. 정리 대상 워크플로우 5건을 선택하기 전에 '연결된 리소스' 버튼으로 함께 내려갈 채팅 앱이 없는지 확인한 뒤, **배포 중지 → 확인**을 누릅니다. 관리자 신청이라 결재 없이 바로 실행되고 "배포 중지가 시작되었습니다." 메시지가 표시됩니다.

#### 시나리오 2 — 개발자가 본인 워크플로우를 정리하고 결재를 받는다

개발자가 **마이페이지 > 일괄 제어** 탭에서 본인이 만든 워크플로우 중 오래 쓰지 않은 2건을 선택해 신청합니다. "배포 중지가 신청되었습니다." 메시지가 뜨고, 두 행에 **승인 대기 중** 배지가 붙습니다. 결재자에게 알림이 가고, 결재자가 **검토** 모달에서 함께 내려갈 채팅 앱까지 확인한 뒤 승인하면 실행됩니다.

#### 시나리오 3 — 잘못 신청한 건을 되돌린다

신청 직후 대상 하나가 아직 사용 중이라는 사실을 알게 됩니다. 신청자가 목록에서 해당 행의 **배포 중지 취소**를 누르면, 같은 신청에 묶인 다른 워크플로우까지 함께 철회된다는 안내를 확인하고 취소합니다. 배지가 사라지고, 정말 중지할 건만 다시 선택해 신청합니다.

#### 시나리오 4 — 카나리 때문에 선택되지 않는다

목록에 있는 워크플로우의 체크박스가 회색이라 선택되지 않습니다. 체크박스에 마우스를 올리니 "카나리가 진행 중입니다. 전면 전환 또는 원복 후 중지할 수 있습니다."가 표시됩니다. 워크플로우 화면에서 카나리를 전면 전환으로 정리한 뒤 일괄 제어로 돌아와 다시 선택합니다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://genos-docs.gitbook.io/default/v1.9.4/admin-management/settings/bulk-control.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.