// back-office

감사 추적·원본 백업

분기 감사나 재실행에 대비해 원본을 남겨야 할 때. 받은 데이터를 가공 없이 그대로 보존합니다.

// 상황

이런 상황이라면

재실행이 안 된다

가공만 해 두고 원본을 버리면, 나중에 같은 시점 데이터를 다시 만들 수 없습니다.

감사 때 근거가 없다

분기 감사에서 출처를 물으면 원본이 있어야 답할 수 있습니다.

백업이 흩어져 있다

여기저기 받아 둔 파일은 시점도 형식도 제각각입니다.

// 흐름

어떻게 동작하나

  1. 01

    수집

    필요한 데이터를 받습니다.

  2. 02

    원본 보존

    받은 결과를 가공 없이 그대로 저장합니다.

  3. 03

    주기 백업

    정해진 주기로 같은 수집을 돌려 보관 이력을 쌓습니다.

// 결과물

손에 남는 것

  • 받은 원본을 가공 없이 보존
  • 같은 시점 데이터 재실행 가능
  • 감사 추적용 출처 확보
  • 주기적 백업 이력 축적

// 실행 가이드

그대로 따라 하면 됩니다

사전 점검부터 검증까지 이 페이지에서 끝납니다. 실행 방식이 여럿이면 하나만 고르면 됩니다.

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
전체 가이드 페이지로 보기

// 더 보기

관련 시나리오

// faq

자주 묻는 질문

원본 형식 그대로 받을 수 있나요?

표준 데이터 형식 결과를 그대로 저장하면 가공 전 상태를 보존할 수 있습니다.

백업을 자동화할 수 있나요?

스케줄러나 GitHub Actions 로 주기 백업을 돌릴 수 있습니다.

얼마나 오래 보관하나요?

보관 위치와 기간은 내부 정책에 맞춰 정합니다. 받은 결과는 저장한 곳에 남습니다.

// related

함께 보면 좋은 흐름

같은 데이터를 제품 연동, 내부 시스템, 자동화 작업 중 어디에 둘지에 따라 구현 방식이 달라집니다.

headless

첫 수집은 작게 시작합니다

가입하고 API 키를 만드세요. 짧은 기간의 데이터로 응답 형식을 먼저 확인할 수 있습니다.