전체 활용 사례

// 팀 워크플로우에 녹여내기

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

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

GitHub ActionsCLI매주 월요일 09:00 KST

이런 분께 원본 CSV 가 그대로 git 에 남아야 하는 감사 추적 팀.

Openbackup/2026-W18

weekly backup · 2026-W18 · 3 banks

  • weekly-tx-2026-W18-ibk.csv
  • weekly-tx-2026-W18-kb.csv
  • weekly-tx-2026-W18-shinhan.csv
  • +1개 파일

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 조건 추가