GitHub Actions 워크플로 뷰어

VMark는 GitHub Actions 워크플로 YAML을 인터랙티브한 방향성 비순환 그래프(DAG)로 렌더링하며, 작업, 단계, 트리거를 구조화된 폼을 통해 편집할 수 있게 해 줍니다 — 기본 파일의 주석, 앵커, 서식을 잃지 않고 말이죠.

이 기능은 두 가지 표면에서 작동합니다:

1. .github/workflows/ 아래의 단독 .yml 파일 (또는 최상위 구조가 워크플로와 일치하는 모든 파일): 왼쪽에 소스를, 오른쪽에 인터랙티브 캔버스 + 폼 편집기를 두는 분할 뷰.
2. 마크다운 코드 펜스: 백틱 세 개의 yaml 또는 yml 펜스 블록에 인식 가능한 워크플로가 포함되어 있으면, VMark는 mermaid 블록이 렌더링되는 것과 같은 방식으로 이를 Mermaid 스타일의 DAG로 인라인 렌더링합니다.

단독 워크플로 파일

VMark에서 .github/workflows/*.yml 파일을 엽니다. 오른쪽 사이드 패널이 자동으로 열리며 다음을 표시합니다:

• 인터랙티브 React Flow 캔버스로 표현된 전체 워크플로(작업은 노드로, needs: 의존성은 엣지로).
• 캔버스 아래의 구조화된 편집기 패널.
• 편집기 헤더의 저장 / 취소 컨트롤.

캔버스에서 작업을 클릭하여 편집합니다. 작업 내부의 단계를 클릭하여 해당 단계를 편집합니다.

작업 편집

편집 가능한 필드:

필드	패치 종류
name	job.set
runs-on	job.set
if	job.set

읽기 전용 요약: 단계 수, needs:, uses:(재사용 가능한 워크플로 작업의 경우).

단계 편집

편집 가능한 필드:

필드	패치 종류
name	step.set
run (run 단계의 경우)	step.set
working-directory	step.set
if	step.set
with: 키	with.set / with.remove

with: 블록은 키/값 행을 추가/편집/제거하는 형태로 렌더링됩니다. 키 이름을 변경하면 이전 키에 대한 with.remove 다음에 새 키에 대한 with.set이 발행됩니다.

uses: 단계의 경우, 액션 참조 자체는 읽기 전용입니다 — 다른 액션이 필요하다면 소스에서 변경하세요.

트리거

트리거 요약(이벤트, 브랜치, 태그, 경로, cron, 타입)은 이 버전에서 읽기 전용입니다. 단일 줄 입력으로 밀집된 트리거 구조를 편집하는 것은 손실이 너무 큽니다. 전용 선택기가 출시될 때까지 소스에서 트리거를 편집하세요.

편집 저장

필드를 변경하면 편집 사항이 메모리 내 패치 목록에 큐잉됩니다. 저장 버튼은 현재 개수를 표시합니다(예: 저장되지 않은 항목 3개).

저장을 클릭하면 VMark는 다음을 수행합니다:

1. 에디터에서 현재 YAML을 읽습니다.
2. 큐잉된 모든 패치를 YAML의 CST(구체적 구문 트리)에 적용합니다 — 주석, 앵커, 기존 서식을 보존하면서.
3. 마치 사용자가 입력한 것처럼 결과를 다시 에디터에 씁니다.

파일은 일반적인 의미에서 더티 상태가 됩니다. 디스크에 쓰려면 Cmd+S를 누르세요.

서식 보존

기본 저장 경로는 모든 패치를 yaml 패키지의 CST API를 통해 실행합니다 — 주석, 앵커 노드, 사용자 지정 들여쓰기, 기존의 플로우 vs 블록 스타일 선택이 보존됩니다.

표준화된 재서식 출력을 선호한다면 설정 → 고급에서 저장 시 YAML 서식 보존을 끄세요. 재서식 경로는 주석을 삭제하므로, 이 옵션은 명시적으로 활성화해야 합니다.

마크다운의 코드 펜스

YAML 코드 펜스에 워크플로를 입력합니다:

```yaml
name: ci
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm test
```

VMark는 워크플로의 형태(작업당 runs-on이 있는 최상위 jobs:)를 감지하여 다이어그램을 인라인으로 렌더링합니다. 다이어그램은 읽기 전용입니다 — 워크플로를 변경하려면 소스를 편집하세요.

진단

VMark는 소스 옆에 파싱 + 린트 진단을 표시합니다:

코드 접두사	의미
GHA-PARSE-*	잘못된 형식의 YAML 또는 누락된 필수 키
GHA-JOB-*	작업 수준 문제(중복 ID, 충돌하는 uses: + steps:)
GHA-NEEDS-*	의존성 문제(알 수 없는 참조, 사이클)
GHA-STEP-*	단계 수준 문제
GHA-EXPR-*	알 수 없는 컨텍스트 참조
GHA-MATRIX-*	매트릭스 확장 문제
GHA-SEC-*	보안 경고(예: pull_request_target 체크아웃 패턴)
GHA-ACTIONLINT-*	설치된 경우 actionlint에서 전달됨

더 풍부한 표현식 진단을 위해 actionlint를 설치하고 설정 → 고급에서 사용 가능한 경우 actionlint 사용을 켜세요.

액션 메타데이터

공개 GitHub Actions를 참조하는 uses: 단계의 경우, VMark는 각 액션의 action.yml을 가져와 구조화된 편집기에서 입력 설명을 채울 수 있습니다. 이 옵션은 명시적으로 활성화해야 하며, 24시간 동안 디스크에 캐시됩니다.

설정 → 고급에서 액션 메타데이터 가져오기를 토글하세요. 모든 액션 참조를 순수 텍스트로 유지하려면 비활성화하세요 — 네트워크 요청은 발생하지 않습니다.

내보내기

워크플로 사이드 패널에는 헤더 메뉴에서 접근 가능한 세 가지 내보내기 옵션이 포함되어 있습니다:

형식	용도
Mermaid	README 및 기타 마크다운 문서에 임베드. 손실 있음: 실행 상태, 액션 아이콘, 사용자 지정 배지, 매트릭스 확장 세부 정보를 생략합니다.
SVG	벡터 그래픽이 필요한 문서에 임베드. HTML 콘텐츠에 foreignObject를 사용합니다.
PNG	채팅 또는 SVG가 지원되지 않는 곳에서 공유. 캔버스의 현재 줌으로 렌더링됩니다.

이 기능이 아닌 것

VMark는 GitHub Actions 워크플로를 실행하지 않습니다. 뷰어이자 편집기일 뿐 — 실행은 GitHub의 역할로 남습니다. 이 기능은 순전히 워크플로 YAML을 읽고, 검토하고, 작성하기 위한 것입니다.