G7 워크플로 자동화 모듈 - Glitter Workflow

개요

Gnuboard7에서 발생하는 여러 이벤트를 조건과 작업으로 연결할 수 있는
Workflow & Automation 모듈을 만들어 보았습니다.

Glitter Workflow 0.18.0

Trigger → Conditions → Actions → Execution

쉽게 말하면,

“어떤 일이 발생했을 때 → 조건을 확인하고 → 정해진 작업들을 순서대로 실행한다.”

라는 구조입니다.

---

왜 만들었나

G7에는 이미 Hook, Queue, Notification, Permission 등 여러 기반 기능이 있습니다.

그런데 실제 사이트를 운영하다 보면 이런 요구가 계속 생깁니다.

• 회원이 가입하면 어떤 작업을 실행하고 싶다.
• 회원 정보가 변경되면 외부 시스템에 알려주고 싶다.
• 게시물이 등록되면 특정 조건에서 후속 작업을 실행하고 싶다.
• 작업을 바로 실행하지 않고 일정 시간 뒤에 처리하고 싶다.

이런 요구를 하나씩 코드에 직접 붙이기 시작하면 결국 각각의 기능이 서로 강하게 결합됩니다.

그래서 새로운 이벤트 시스템을 만드는 대신,

G7에서 이미 발생하는 이벤트를 받아서 자동화 흐름으로 연결하는 계층

을 만들어 보기로 했습니다.

그 결과가 Glitter Workflow입니다.

---

기본 구조

워크플로 하나는 크게 네 단계로 구성됩니다.

1. Trigger

워크플로를 시작시키는 이벤트입니다.

현재 지원하는 Trigger는 다음과 같습니다.

• user.registered
• user.updated
• board.post.created
• board.comment.created

내부적으로는 G7/Core 및 관련 모듈의 Hook과 연결되지만, Workflow에서는 별도의 안정적인 Trigger Key를 사용합니다.

예를 들어 내부 Hook 이름이 그대로 워크플로 정의에 노출되는 구조는 피했습니다.

---

2. Conditions

Trigger가 발생했다고 해서 항상 Action을 실행할 필요는 없습니다.

조건을 지정해서 실행 여부를 판단할 수 있습니다.

조건 묶음은 기본적으로 다음 두 방식을 지원합니다.

• all
• any

즉,

회원 정보가 변경됐고
특정 조건까지 만족한다면
다음 Action을 실행한다.

같은 흐름을 만들 수 있습니다.

조건에서 접근할 수 있는 데이터 역시 무제한으로 열어놓지 않고, Workflow가 허용하는 Context Schema 안에서 사용하도록 제한했습니다.

---

3. Actions

조건을 통과하면 Action들을 순차적으로 실행합니다.

0.18.0에서 실제 실행 가능한 Action은 두 가지입니다.

• delay
• webhook

Delay

다음 작업을 일정 시간 뒤에 실행합니다.

단순한 기능처럼 보이지만 Queue 환경에서는 재시도, 중복 실행, stale-running 상태 등을 함께 고려해야 하기 때문에 실행 상태를 별도로 관리하도록 구성했습니다.

Webhook

외부 HTTP endpoint로 요청을 전달할 수 있습니다.

Webhook 실행에서는 단순히 URL을 받아서 호출하는 것보다 outbound 요청의 안전 경계와 실행 추적에 더 신경을 썼습니다.

민감한 response body나 credential을 관리 화면에 그대로 노출하지 않고, 운영에 필요한 제한된 metadata만 남깁니다.

---

Execution

Workflow가 실행되면 실행 이력을 별도로 관리합니다.

대략적인 관계는 다음과 같습니다.

Workflow
   │
   ├── Trigger
   │
   ├── Conditions
   │
   └── Actions
          │
          ▼
     Execution
          │
          ├── Action Execution #1
          ├── Action Execution #2
          └── Action Execution #3

Execution에서는 다음과 같은 상태를 사용합니다.

• pending
• scheduled
• running
• succeeded
• failed
• cancelled
• skipped

관리자는 Execution 목록과 상세 화면에서 실행 상태와 안전한 범위의 trace metadata를 확인할 수 있습니다.

correlation_id, causation_id, depth 같은 정보도 보존하여 나중에 자동화 흐름이 복잡해졌을 때 실행 관계를 추적할 수 있도록 했습니다.

---

Trigger를 바로 실행하지 않는 이유

이 부분은 만들면서 꽤 중요하게 본 부분입니다.

이벤트가 들어왔다고 해서 Hook listener 안에서 워크플로 전체를 바로 실행시키는 구조로 만들지는 않았습니다.

Trigger를 정규화하고 필요한 Context만 추출한 뒤 Acceptance를 거쳐 Queue 기반 실행 흐름으로 넘깁니다.

즉,

G7 Event / Hook
      │
      ▼
Workflow Trigger
      │
      ▼
Normalize / Redact
      │
      ▼
  Acceptance
      │
      ▼
    Queue
      │
      ▼
  Execution

과 같은 구조입니다.

원본 Model이나 Hook argument 전체를 Workflow runtime에 그대로 던지는 것도 피했습니다.

필요한 정보만 정규화하고, Workflow가 소유하는 Context Schema로 경계를 만드는 방식입니다.

---

관리자 화면

현재 관리자 영역은 크게 세 부분으로 구성되어 있습니다.

Workflows

워크플로를 생성하고 수정하고 활성화할 수 있습니다.

목록에서는

• 상태
• Trigger
• 이름
• Public UUID

기준으로 필터링하거나 검색할 수 있습니다.

목록 정렬은

created_at DESC, id DESC

방식으로 결정적으로 유지합니다.

외부에 노출되는 Workflow 식별자는 UUID이며, 내부 numeric ID는 public contract로 사용하지 않습니다.

Executions

워크플로 실행 결과를 확인하는 영역입니다.

상태와 Trigger 기준 필터를 지원하며, 상세 화면에서는 Action Execution과 Acceptance를 포함한 실행 추적 정보를 확인할 수 있습니다.

단, 다음과 같은 정보는 의도적으로 노출하지 않습니다.

• raw context
• raw payload
• Action 전체 config
• response body
• secrets
• exception object
• stack trace

운영에 필요한 정보와 내부 구현 정보를 분리하려고 했습니다.

Settings

현재 일부 Workflow runtime 설정을 관리할 수 있습니다.

Connection Registry도 내부 구조는 존재하지만 0.18.0에서는 Connection 인증정보나 Secret을 관리하는 UI까지 열어놓지는 않았습니다.

---

일부러 넣지 않은 기능

Workflow라고 하면 기능을 계속 붙이고 싶어집니다.

그런데 자동화 시스템은 기능을 쉽게 추가하는 것보다 어디까지 실행할 수 있게 허용할 것인가가 더 중요하다고 생각했습니다.

그래서 현재는 다음과 같은 기능을 제공하지 않습니다.

• 임의 PHP 실행
• 임의 JavaScript 실행
• SQL 실행
• Shell command 실행
• 임의 Hook emission
• Workflow → Workflow 호출
• Loop
• Branch runtime
• 범용 third-party Trigger registry

또한 notification Action은 이름과 타입은 예약되어 있지만 현재 실행할 수 없는 상태입니다.

G7의 기존 Notification 체계를 활용하는 것이 맞다고 보고 있지만, recipient/auth/idempotency 등의 계약을 충분히 확인하지 않은 상태에서 별도의 구현을 먼저 넣고 싶지는 않았습니다.

Execution의 Retry/Cancel 역시 마찬가지입니다.

버튼 하나 추가하는 문제라기보다 Queue와 외부 side effect가 존재하는 상황에서 어떤 상태를 안전하게 되돌리거나 다시 실행할 수 있는지부터 정의되어야 하기 때문에 현재 버전에서는 열지 않았습니다.

---

중복 실행과 실행 추적

자동화 시스템에서 상당히 신경 쓰이는 부분이 중복 실행입니다.

Glitter Workflow는 실행 UUID와 Action index, Workflow version 등을 이용해 실행 단위를 구분합니다.

Webhook에도 안정적인 delivery identifier를 사용합니다.

다만 이것을 과장해서 “모든 상황에서 exactly-once를 보장한다”고 표현하지는 않습니다.

특히 source event가 Workflow Acceptance에 들어오기 전의 구간까지 모듈 하나가 완전한 at-least-once를 보장할 수 있는 구조는 아닙니다.

현재 보장할 수 있는 경계와 보장할 수 없는 경계를 가능하면 명시적으로 나누려고 했습니다.

---

G7 기능을 다시 만들지 않는 방향

Glitter Workflow를 만들면서 세운 원칙 중 하나는

G7에 이미 있는 기능을 Workflow 안에서 다시 만들지 않는다

였습니다.

가능하면 기존의

• Hook
• Queue
• Permission
• Notification
• HTTP/Outbound infrastructure

등을 사용하고, Workflow는 그 위에서 자동화의 정의와 실행 상태를 관리하는 역할에 집중합니다.

그래서 이 모듈은 거대한 별도 자동화 플랫폼이라기보다

G7의 여러 기능 사이를 연결하는 orchestration layer

에 더 가깝습니다.

---

현재 규모

0.18.0 기준으로 현재 모듈은 대략 다음 정도의 구성을 가지고 있습니다.

• Source files: 73
• Database migrations: 7
• Module routes: 12
• Documentation: 9
• Tests: 10
• 전체 non-vendor files: 134

Database에서는 Workflow 정의뿐 아니라 Execution, Action Execution, Acceptance를 각각 관리합니다.

---

G7에 집중한 자동화 엔진

Glitter Workflow는 Zapier나 n8n 같은 범용 자동화 플랫폼을 지향하지 않습니다.

대신,

G7이라는 애플리케이션 안에서 예측 가능한 이벤트와 제한된 Action을 안전하게 연결하는 것

에 초점을 맞추고 있습니다.

기능의 범위를 무작정 넓히기보다는, Trigger capture → 조건 평가 → 순차 Action → Queue → 실행 기록이라는 Workflow runtime의 기본 골격과 실행 경계를 먼저 갖추는 방향으로 만들었습니다.

---

0.18.0

이번 0.18.0을 첫 공개 버전으로 배포합니다.

현재 production 환경에서도 동일한 0.18.0을 기준으로 운영 검증했으며, bundled source / installed module / DB registry의 버전을 일치시킨 상태에서 최종 release baseline을 잡았습니다.

다만 production DB와 격리된 테스트 환경임을 증명할 수 없는 테스트는 운영 데이터를 보호하기 위해 실행하지 않았습니다.

아직 부족한 부분도 많고, 일부 기능은 구현 방법을 몰라서라기보다 안전하게 공개할 계약이 정해지지 않아 의도적으로 막아놓은 상태입니다.

그 부분들도 G7의 구조와 맞춰가면서 하나씩 풀어볼 생각입니다.

---

Glitter Workflow 0.18.0
Workflow & Automation for Gnuboard7

작은 이벤트들을 연결해서
조금 더 큰 흐름을 만들어 보는 모듈입니다.

---

요구 사항

• GnuBoard7 >= 7.0.11
• PHP >= 8.2
• Laravel 12 compatible environment
• MariaDB
• Queue Worker

---

의존성 필수 확장

Glitter Workflow는 다음 GnuBoard7 확장을 필요로 합니다.

게시판 모듈

sirsoft-board >= 1.1.2

---

관리자 페이지에서 설치

1. GitHub 저장소에서 설치 (권장)

관리자 → 모듈 관리 → 수동 설치 → GitHub

아래의 저장소 URL을 입력합니다.

https://github.com/glitter-node/glitter-workflow

설치가 완료된 후 Glitter Workflow 모듈을 활성화하면 관리자 메뉴에 워크플로 관리가 생성됩니다.

2. ZIP 패키지 설치

GitHub Release에서 zip 패키지를 다운로드합니다.

• Glitter Workflow 0.18.0 ZIP 모듈 패키지를 다운로드

ZIP 패키지를 다운로드한 후

관리자 → 모듈 관리 → 수동 설치 → 파일 업로드

방식으로 설치할 수도 있습니다.

3. 설치 후 페이지 로드 오류 발생 시

관리자 → 환경설정 → 고급 → 캐시 모두 삭제

를 실행한 후 다시 확인합니다.

---

저장소

GitHub

https://github.com/glitter-node/glitter-workflow

Release

https://github.com/glitter-node/glitter-workflow/releases/tag/v0.18.0

---

라이선스

MIT License.

Copyright (c) 2026 Glitter.kr

---

최적의 설치

이 버전은 ZIP 설치보다 GitHub 저장소 설치를 권장합니다.

G7 관리자에서 GitHub 저장소 URL을 이용해 설치하면 모듈 업데이트와 버전 관리 흐름을 유지하기 쉽습니다.

https://github.com/glitter-node/glitter-workflow