headless

// use case

감사 추적 · 백업

원본 CSV 가 그대로 git 에 남습니다. 분기 감사 · 재실행에 그대로.

// scenario

감사 · 재실행용 Artifact 보존

PR 없이 GitHub Artifact 로 최대 90일 보존. 회계 시스템에 직접 import 하고 git 에 둘 필요 없는 경우.

주기
임의 cron
대상
분기 감사 때 한 번 다운받으면 되는 팀.
채널
GitHub Actions

01사전 점검

아래 명령을 그대로 붙여넣어 지금 내 환경이 준비됐는지 확인한다.

  • repo secret H6S_API_KEY 가 등록돼 있다

    gh secret list

    목록에 H6S_API_KEY 가 보인다

    아니면 — gh secret set H6S_API_KEY # 또는 repo Settings → Secrets

  • 워크스페이스에 대상 자격증명이 있다

    h6s credentials list

    그 기관에 매칭되는 자격증명이 1건 이상 보인다

    아니면 — h6s credentials create --interactive --cert

02실행

아래 파일을 .github/workflows/ 에 저장하고 기본 브랜치에 commit. 첫 검증은 Actions 탭 → Run workflow 로 수동 트리거.

yaml
# 수집 결과를 GitHub Artifact 로 90일간 보존.
# Repo 에 commit 하지 않고 별도 보존만 필요한 경우 (감사·재실행·로컬 다운로드 용도).
name: 수집 결과 Artifact 보존

on:
  schedule:
    - cron: '0 0 1 * *'   # 매월 1일
  workflow_dispatch: {}

jobs:
  fetch:
    runs-on: ubuntu-latest
    steps:
      - id: prev-month
        run: echo "value=$(date -u -d '1 month ago' +%Y-%m)" >> "$GITHUB_OUTPUT"

      - id: fetch
        uses: bolta-io/h6s-action@v0
        with:
          api-key: ${{ secrets.H6S_API_KEY }}
          schema: bank.transactions.cb.v1
          provider: CB_IBK
          month: ${{ steps.prev-month.outputs.value }}

      - uses: actions/upload-artifact@v4
        with:
          name: h6s-bank-${{ steps.prev-month.outputs.value }}
          path: ${{ steps.fetch.outputs.path }}
          retention-days: 90
          if-no-files-found: error

PR·commit 권한 불필요. repo secret H6S_API_KEY 하나면 끝.

03검증

  • Actions 탭 워크플로우가 초록.
  • run 페이지 하단 Artifacts 에 h6s-bank-YYYY-MM 이 보인다.
  • 로컬에서 gh run download <run-id> 로 받아진다.

04흔한 에러

fetch step 에서 NO_API_KEY 로 실패

secret 이름이 yml 의 secrets.H6S_API_KEY 와 다르다.

해결 secret 을 정확히 H6S_API_KEY 로 등록.

CREDENTIAL_INSUFFICIENT_FOR_PROVIDER

그 provider 에 매칭되는 자격증명이 워크스페이스에 없다.

해결 h6s credentials create --interactive --cert (공동인증서 1개로 전 기관 공용).

cron 시간이 지나도 안 돈다

yml 이 기본 브랜치에 없거나, repo 가 60일 비활성이라 scheduled workflow 가 멈췄다.

해결 기본 브랜치에 머지하고, 가끔 수동 트리거해 활성 유지.

05변형

같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.

보존 기간 변경

yaml
retention-days: 30   # 최대 90

다른 schema 로 교체

yaml
schema: hometax.tax-invoices.sales.v1
          provider: HOMETAX

// scenario

주간 입출금내역 백업 (GitHub Actions)

매주 등록된 전 은행 입출금내역을 CSV 로 받아 백업 repo 에 무인 commit. 감사 추적.

주기
매주 월요일 09:00 KST
대상
원본 CSV 가 그대로 git 에 남아야 하는 감사 추적 팀.
채널
GitHub Actions · CLI

01사전 점검

아래 명령을 그대로 붙여넣어 지금 내 환경이 준비됐는지 확인한다.

  • repo secret H6S_API_KEY 가 등록돼 있다

    gh secret list

    목록에 H6S_API_KEY 가 보인다

    아니면 — gh secret set H6S_API_KEY # 또는 repo Settings → Secrets

  • 워크스페이스에 대상 자격증명이 있다

    h6s credentials list

    그 기관에 매칭되는 자격증명이 1건 이상 보인다

    아니면 — h6s credentials create --interactive --cert

  • Slack 알림 (선택)

    gh secret list

    SLACK_WEBHOOK_URL 이 있으면 성공/실패 알림 전송 (없으면 skip)

    아니면 — gh secret set SLACK_WEBHOOK_URL

02실행

백업 전용 repo(예: <your-org>/finance-backup) 의 .github/workflows/weekly-backup.yml 로 저장. 운영자 단말에서 1주일 수동 검증 후 무인 전환 권장.

yaml
# 자기 백업 레포(예: <your-org>/finance-backup) 의 .github/workflows/weekly-backup.yml 로 복사해서 사용.
# Secrets 필요: H6S_API_KEY (필수), SLACK_WEBHOOK_URL (선택)
# 자세한 절차: ../references/scenario-weekly-backup.md

name: weekly-backup

on:
  schedule:
    - cron: '0 0 * * 1'  # 매주 월요일 00:00 UTC = 09:00 KST
  workflow_dispatch:

permissions:
  contents: write  # 자동 commit & push

env:
  H6S_API_KEY: ${{ secrets.H6S_API_KEY }}
  SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
  INTERNAL_FINANCE_OUTPUT_DIR: ./out

jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install h6s CLI
        run: npm i -g @h6s-ai/cli

      - name: Verify auth
        run: h6s me

      - name: Resolve week range
        id: range
        run: |
          # 월요일 00:00 UTC cron — 7일 전 = 지난 월요일, 1일 전 = 지난 일요일
          WEEK_START=$(date -u -d '7 days ago' +%F)
          WEEK_END=$(date -u -d '1 day ago' +%F)
          echo "start=$WEEK_START" >> "$GITHUB_OUTPUT"
          echo "end=$WEEK_END"     >> "$GITHUB_OUTPUT"

      - name: List bank providers
        id: providers
        run: |
          # CB_BANK 유형 자격증명만 추출 (HOMETAX / CARD 제외)
          PROVIDERS=$(h6s credentials list --output json \
            | jq -r '[.credentials[] | select(.providerCategory == "BANK") | .providerCode] | unique | join(" ")')
          echo "list=$PROVIDERS" >> "$GITHUB_OUTPUT"

      - name: Fetch weekly transactions
        run: |
          mkdir -p out
          PROVIDERS="${{ steps.providers.outputs.list }}"
          if [ -z "$PROVIDERS" ]; then
            echo "::warning::BANK 자격증명이 없어 입출금내역 수집 스킵"
            exit 0
          fi
          for PROVIDER in $PROVIDERS; do
            h6s fetch bank.transactions.cb.v1 \
              --provider "$PROVIDER" \
              --from "${{ steps.range.outputs.start }}" \
              --to "${{ steps.range.outputs.end }}" \
              --output csv \
              --save "out/weekly-tx-${{ steps.range.outputs.end }}-$PROVIDER.csv" \
              --quiet --no-color || echo "::warning::$PROVIDER fetch failed"
          done

      - name: Fetch balance snapshot
        run: |
          h6s fetch bank.accounts.cb.v1 \
            --output csv \
            --save "out/weekly-balance-${{ steps.range.outputs.end }}.csv" \
            --quiet --no-color

      - name: Commit and push
        run: |
          git config user.name 'h6s-bot'
          git config user.email 'h6s-bot@users.noreply.github.com'
          git add out/
          if git diff --cached --quiet; then
            echo "변경 없음 — commit skip"
          else
            git commit -m "주간 백업 ${{ steps.range.outputs.start }} ~ ${{ steps.range.outputs.end }}"
            git push
          fi

      - name: Notify Slack on failure
        if: failure() && env.SLACK_WEBHOOK_URL != ''
        run: |
          curl -sX POST -H 'Content-Type: application/json' "$SLACK_WEBHOOK_URL" \
            -d '{"text": "⚠️ weekly-backup-action 실패 — ${{ github.repository }}/actions/runs/${{ github.run_id }}"}'

      - name: Notify Slack on success
        if: success() && env.SLACK_WEBHOOK_URL != ''
        run: |
          curl -sX POST -H 'Content-Type: application/json' "$SLACK_WEBHOOK_URL" \
            -d '{"text": "✅ 주간 백업 완료 ${{ steps.range.outputs.start }} ~ ${{ steps.range.outputs.end }}"}'

BANK 자격증명을 자동 탐색해 등록된 전 은행을 도므로 provider 하드코딩이 없다.

03검증

  • Actions(backup repo)가 초록, out/ 에 weekly-tx-<날짜>-<PROVIDER>.csv + weekly-balance CSV.
  • 변경분만 자동 commit & push (변경 없으면 commit skip 로그).
  • 실패/성공 시 SLACK_WEBHOOK_URL 있으면 알림 1줄.

04흔한 에러

fetch step 에서 NO_API_KEY 로 실패

secret 이름이 yml 의 secrets.H6S_API_KEY 와 다르다.

해결 secret 을 정확히 H6S_API_KEY 로 등록.

CREDENTIAL_INSUFFICIENT_FOR_PROVIDER

그 provider 에 매칭되는 자격증명이 워크스페이스에 없다.

해결 h6s credentials create --interactive --cert (공동인증서 1개로 전 기관 공용).

cron 시간이 지나도 안 돈다

yml 이 기본 브랜치에 없거나, repo 가 60일 비활성이라 scheduled workflow 가 멈췄다.

해결 기본 브랜치에 머지하고, 가끔 수동 트리거해 활성 유지.

05변형

같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.

특정 은행만 백업

yaml
# providers step 의 jq select 에 providerCode 조건 추가

// related

다른 각도에서 보기

headless

Get started

지금 가입하고 API 키를 발급받으세요.