// 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 로 수동 트리거.
# 수집 결과를 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: errorPR·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변형
같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.
보존 기간 변경
retention-days: 30 # 최대 90다른 schema 로 교체
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 --certSlack 알림 (선택)
gh secret listSLACK_WEBHOOK_URL 이 있으면 성공/실패 알림 전송 (없으면 skip)
아니면 —
gh secret set SLACK_WEBHOOK_URL
02실행
백업 전용 repo(예: <your-org>/finance-backup) 의 .github/workflows/weekly-backup.yml 로 저장. 운영자 단말에서 1주일 수동 검증 후 무인 전환 권장.
# 자기 백업 레포(예: <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변형
같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.
특정 은행만 백업
# providers step 의 jq select 에 providerCode 조건 추가// related