GitHub Actions: Sume Format으로 릴리스 영상 만들기

GitHub Actions로 릴리스 영상을 만들려면 types: [published]를 지정한 release 이벤트에서 워크플로를 실행하고, 릴리스 노트는 input에, 태그는 Idempotency-Key에 담아 Sume Format 실행을 시작하고, 실행이 끝날 때까지 폴링한 다음, primary_output_url을 내려받아 gh release upload로 파일을 첨부하세요.

Sume가 제공하는 GitHub Action은 없고 Sume CLI에는 영상 명령어가 없으므로, Sume 단계는 curl로 하는 평범한 HTTPS 호출입니다. Sume 관련 사실은 Format 호출하기 (영문), 실행과 결과 (영문), Format 쿡북에서, GitHub 동작은 GitHub 자체 문서에서 가져왔으며, 모두 2026-09-27에 확인했습니다. 파이프라인에서 Sume CLI를 쓰는 방법은 CI에서 Sume CLI 실행하기를 참고하세요.

첫 실행 전에 무엇이 필요한가요?

한 번만 설정해 두면 되는 것이 세 가지 있습니다.

• 릴리스 노트를 영상으로 바꾸는 자체 Format: 이 글에서는 자리표시자 주소 acme/release-video를 씁니다. Sume Format이란?을 참고하세요.
• formats:read와 formats:write가 있는 Sume API 키: 팀 Format에는 그 팀 워크스페이스에서 만든 키가 필요하며, 서비스 계정 키로는 Format 실행을 만들 수 없습니다.
• SUME_API_KEY라는 이름의 리포지토리 시크릿으로 저장한 키: Sume 문서는 키를 둘 수 있는 곳으로 CI 시크릿 저장소를 꼽습니다. 시크릿이 없으면 GitHub 표현식은 빈 문자열을 돌려주고, Sume는 401 unauthorized로 응답합니다.

릴리스가 게시되면 실행을 어떻게 시작하나요?

release 이벤트에서 GITHUB_REF는 태그 ref인 refs/tags/<tag_name>이므로 GITHUB_REF_NAME이 곧 태그입니다. 이 작업은 이벤트 페이로드의 릴리스 설명을 NOTES에 복사하고, jq로 요청 본문을 만들고, 실행을 시작한 다음, 다음 단계를 위해 실행 ID를 저장합니다.

on:
  release:
    types: [published]
permissions:
  contents: write
jobs:
  video:
    runs-on: ubuntu-latest
    timeout-minutes: 100
    env:
      SUME_API_KEY: ${{ secrets.SUME_API_KEY }}
      NOTES: ${{ github.event.release.body }}
    steps:
      - name: Start the Format run
        run: |
          jq -n --arg tag "$GITHUB_REF_NAME" --arg notes "$NOTES" \
            '{input: {tag: $tag, release_notes: $notes}, generation_spend_cap_usd: 20}' > body.json
          curl -sS -X POST https://api.sume.com/v1/formats/acme/release-video/runs \
            -H "Authorization: Bearer $SUME_API_KEY" -H "Content-Type: application/json" \
            -H "Idempotency-Key: release-video-$GITHUB_REF_NAME-v1" -d @body.json > run.json
          RUN_ID=$(jq -er .data.id run.json) || { cat run.json; exit 1; }
          echo "RUN_ID=$RUN_ID" >> "$GITHUB_ENV"

왜 노트는 input에, 태그는 키에 넣나요?

각 선택은 양쪽 중 한쪽의 규칙을 따릅니다.

• NOTES는 일부러 둔 중간 환경 변수입니다. GitHub는 body로 끝나는 컨텍스트를 신뢰할 수 없는 입력일 수 있다고 보며, 인라인 스크립트에서는 중간 환경 변수를 권장 방식으로 꼽습니다.
• 노트는 instruction이 아니라 input에 넣습니다. Sume는 input을 실행 워크스페이스의 파일로 기록하고, 에이전트에게 그것이 지시가 아니라 호출자가 넘긴 데이터라고 알려 줍니다. input은 최상위 키 최대 64개, 최대 2 MiB까지 받습니다.
• 키는 태그로 만듭니다. 같은 키와 같은 본문으로 보내면 200과 원래 실행이 돌아오므로, 워크플로를 다시 실행해도 두 번 지불하지 않습니다. 같은 태그로 새 영상을 만들고 싶으면 -v1의 버전 번호를 올리세요.
• generation_spend_cap_usd는 이 실행이 쓸 수 있는 금액에 상한을 두며, 최대 $500까지 설정할 수 있습니다. 규칙은 무인 에이전트의 지출 상한에서 다룹니다.

작업은 영상을 어떻게 기다리나요?

Sume 쿡북은 웹훅 대신 백오프로 폴링할 경우의 하나로 CI 작업을 꼽습니다. 두 번째 단계는 5초에서 시작해 60초까지 두 배씩 늘어나는 간격으로 GET /v1/format-runs/{run_id}를 읽고, 읽기 실패는 한 번 더 기다리는 것으로 처리합니다. 실행이 계속 작업하는 동안 루프 중간에 받는 429나 503은 일시적이기 때문입니다. RUN_ID는 GITHUB_ENV를 통해 넘어오며, GITHUB_ENV는 작업의 이후 단계로 변수를 넘겨 줍니다.

completed가 되면 보여 줄 단 하나의 결과인 primary_output_url이 채워지고, Sume 미디어 URL은 내구성 있는 공개 URL이므로 MP4를 내려받을 때 Sume 키가 필요 없습니다. failed, canceled, skipped도 종료 상태입니다. 이 단계는 실패한 실행의 error를 출력하고 작업을 실패로 끝냅니다.

GitHub CLI는 GitHub 호스팅 러너에 미리 설치되어 있으며, 이를 쓰는 단계마다 GH_TOKEN이 필요합니다. 이 작업은 contents: write를 요청합니다. GitHub의 워크플로 구문 레퍼런스에 따르면 이 권한으로 액션이 릴리스를 만들 수 있습니다. --clobber를 붙이면 다시 실행할 때 같은 이름의 에셋을 교체합니다.

      - name: Wait for the video and attach it
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          SLEEP=5
          while :; do
            RUN=$(curl -sS "https://api.sume.com/v1/format-runs/$RUN_ID" \
              -H "Authorization: Bearer $SUME_API_KEY") || RUN='{}'
            case "$(echo "$RUN" | jq -r '.data.status // empty')" in
              completed) break ;;
              failed|canceled|skipped) echo "$RUN" | jq '.data.error'; exit 1 ;;
            esac
            sleep "$SLEEP"; SLEEP=$(( SLEEP < 60 ? SLEEP * 2 : 60 ))
          done
          curl -sSL --fail -o release-video.mp4 "$(echo "$RUN" | jq -r .data.primary_output_url)"
          gh release upload "$GITHUB_REF_NAME" release-video.mp4 --clobber --repo "$GITHUB_REPOSITORY"

양쪽의 시간 제한은 각각 어떻게 되나요?

GitHub가 작업을 먼저 취소하지 않도록 timeout-minutes는 Sume의 90분 상한을 넘는 값으로 두세요. 그래도 GitHub가 작업을 멈추면 Sume 실행은 계속 진행되며 계속 과금됩니다. 나중에 ID로 다시 읽으세요.

워크플로가 실행되지 않거나 실패한 이유는 무엇인가요?

양쪽에서 확인할 원인은 다음과 같습니다.

• 릴리스가 아직 초안입니다. GitHub는 초안을 만들거나 수정하거나 삭제할 때는 워크플로를 트리거하지 않으며, 초안을 게시하면 published가 발생합니다.
• 다른 워크플로가 GITHUB_TOKEN으로 릴리스를 게시했습니다. 이 토큰으로 트리거된 이벤트는 새 워크플로 실행을 만들지 않으며, GitHub가 나열한 예외에 release는 없습니다.
• 401 unauthorized: 시크릿이 없거나 키가 폐기되었습니다.
• 403 insufficient_scope: 키에 formats:write가 없거나, Formats API가 생기기 전에 만든 키입니다. 스코프는 나중에 추가할 수 없으니 새 키를 만드세요.
• 409 idempotency_conflict: 태그로 만든 키가 다른 본문과 함께 도착했습니다. 예를 들어 노트를 수정한 릴리스를 다시 게시한 경우입니다. 키의 버전을 올리세요.