GitHub Actions 워크플로 뷰어

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

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

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

VMark 자체 워크플로와는 다릅니다

최상위 steps:가 genie/… 또는 action/…을 사용하는 YAML 파일은 Genie 워크플로입니다 — VMark가 실행할 수 있는 VMark 고유의 파이프라인 형식이죠. GitHub Actions 워크플로는 여기서 보고 편집할 수만 있습니다. 이 기능이 아닌 것을 참조하세요.

단독 워크플로 파일

VMark에서 .github/workflows/*.yml 파일을 엽니다. 파일은 분할 뷰로 열립니다 — 왼쪽에 YAML 소스, 오른쪽에 워크플로 워크벤치가 표시됩니다(소스 / 분할 / 미리 보기 토글로 레이아웃을 전환합니다). 워크벤치는 다음을 표시합니다:

• 인터랙티브 React Flow 캔버스로 표현된 전체 워크플로(작업은 노드로, needs: 의존성은 엣지로). 캔버스의 컨트롤 스트립으로 확대·축소하고, 그래프를 창 크기에 맞추고, 레이아웃을 위에서 아래 방향과 왼쪽에서 오른쪽 방향 사이에서 전환할 수 있습니다 — 넓은 창에서 긴 needs: 체인을 볼 때 편리합니다.
• 캔버스 오른쪽 위 모서리의 내보내기 컨트롤(내보내기 참조).
• 캔버스 아래의 구조화된 편집기 패널: 진단 배너, 저장 / 버리기 컨트롤, 워크플로 수준 폼, 그리고 선택한 작업이나 단계에 대한 폼.

캔버스에서 작업을 클릭하여 편집합니다. 작업 내부의 단계를 클릭하여 해당 단계를 편집합니다. Escape 키를 누르면 선택이 해제되고 포커스가 소스로 돌아갑니다.

소스를 편집하는 동안 VMark는 두 창을 동기화합니다: 커서를 작업의 줄로 옮기면 캔버스에서 해당 노드가 강조 표시되고, $ 표현식은 파싱된 워크플로의 컨텍스트를 기준으로 자동 완성되며, 로컬 uses: 참조를 Cmd-클릭하면 대상 파일이 열립니다.

작업 편집

편집 가능한 필드:

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

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

작업 추가(폼 위쪽)는 입력한 ID로 작업을 만듭니다 — ID는 영문자나 밑줄로 시작해야 하고 이미 있는 ID여서는 안 됩니다 — 새 작업은 변경하기 전까지 ubuntu-latest에서 실행됩니다. 작업 폼의 삭제 버튼은 확인을 거친 뒤 선택한 작업을 제거합니다.

작업 폼에는 해당 작업의 단계 목록도 표시됩니다. 각 행은 위나 아래로 옮기거나 (확인을 거친 뒤) 삭제할 수 있으며, 단계 추가는 run: echo TODO 형태의 새 단계를 끝에 추가하므로 바로 편집할 수 있습니다.

단계 편집

편집 가능한 필드:

필드	패치 종류
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: 단계의 경우, 액션 참조 자체는 읽기 전용입니다 — 다른 액션이 필요하다면 소스에서 변경하세요.

트리거

매핑으로 작성된 트리거(on: { push: { branches: [main] } })에는 편집 가능한 필터 필드가 있습니다 — branches, branches-ignore, tags, tags-ignore, paths, paths-ignore, types — 각각 쉼표로 구분된 목록입니다. schedule cron은 읽기 쉬운 문장으로 표시되며, 5분보다 자주 실행되면 경고가 함께 표시되고(GitHub가 이런 일정을 제한합니다), 읽기 전용입니다. 이벤트 이름 하나나 이름 목록으로만 작성된 트리거도 마찬가지로 읽기 전용이니, 소스에서 편집하세요.

권한과 동시성

작업 폼 위에는 워크플로 수준 폼 두 개가 있습니다:

• 권한 — GitHub 기본값(permissions: 키 없음), read-all, write-all, none, 또는 범위별(contents, pull-requests, …)로 각각 read / write / none을 고르는 표.
• 동시성 — group과 cancel-in-progress 여부. 표현식으로 작성된 cancel-in-progress는 표시되지만 여기서 편집할 수는 없습니다.

편집 저장

필드를 변경하면 편집 사항이 메모리 내 패치 목록에 큐잉됩니다. 저장 버튼은 현재 개수를 표시하며(예: 저장 안 됨 3건), 새 작업과 단계는 저장하기 전에도 이미 캔버스와 폼에 나타납니다.

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

1. 에디터에서 현재 YAML을 읽습니다.
2. 큐잉된 모든 패치를 YAML의 CST(구체적 구문 트리)에 적용합니다 — 주석, 앵커, 기존 서식을 보존하면서.
3. 디스크에 있는 파일이라면 결과를 파일에 쓴 다음 에디터를 그에 맞게 갱신합니다 — 단, 그 사이 소스에 입력한 내용이 있으면 입력한 내용이 유지됩니다.

쓰기에 실패해도 잃는 것은 없습니다: 편집 사항이 큐에 그대로 남아 있으므로 다시 저장할 수 있습니다. 제목 없는 문서에는 쓸 파일이 없으므로 저장은 에디터만 갱신합니다. 문서를 저장하려면 Cmd+Shift+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는 워크플로의 형태(최상위 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 사용이 켜져 있으면(기본값은 켜기), VMark는 워크플로 파일의 소스가 바뀔 때마다 로그인 셸 PATH에서 바이너리를 실행하고 그 결과를 GHA-ACTIONLINT-<rule> 태그를 붙여 워크벤치의 진단 배너에 덧붙입니다. 위의 내장 검사는 actionlint를 기다리지 않습니다. 토글이 켜져 있지만 바이너리가 설치되어 있지 않으면 VMark는 세션당 한 번 알리고 그 외에는 조용히 있습니다. 바이너리는 있지만 실행에 실패하면 actionlint 자체의 메시지와 함께 실패를 한 번 보고합니다. actionlint를 완전히 건너뛰려면 토글을 끄세요. MCP workflow.validate 작업은 같은 검사를 필요할 때 실행합니다.

액션 메타데이터

공개 GitHub Actions를 참조하는 uses: 단계의 경우, VMark는 각 액션의 action.yml을 가져와 구조화된 편집기에서 입력 설명을 채웁니다. 결과는 24시간 동안 디스크에 캐시됩니다. 작업 공간 로컬 액션(./…)은 네트워크가 아니라 디스크에서 읽습니다.

워크플로 편집기를 완전히 오프라인으로 유지하려면 설정 → 고급(워크플로 파일)에서 액션 메타데이터 가져오기를 끄세요 — 끄면 네트워크 요청이 전혀 발생하지 않으며, with: 폼은 자유 형식 키/값 행으로 대체됩니다.

내보내기

캔버스 오른쪽 위 모서리의 내보내기 컨트롤은 세 가지 형식을 제공합니다:

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

이 기능이 아닌 것

VMark는 GitHub Actions 워크플로를 실행하지 않습니다. 뷰어이자 편집기일 뿐 — 실행은 GitHub의 역할로 남습니다. 이 기능은 순전히 워크플로 YAML을 읽고, 검토하고, 작성하기 위한 것입니다. VMark 자체의 실행 가능한 파이프라인은 다른 형식입니다: Genie 워크플로를 참조하세요.