headless

// channel

GitHub Action — 정기 수집

cron + h6s-action 으로 PR · Artifact 형태 무인 수신. yml 한 장.

// scenario

월말 입출금내역을 PR 로 받기

매월 1일 09:00 KST 에 전월 한 달치 입출금내역이 별도 브랜치 + PR 로 올라온다. plain-text accounting 의 표준 진입점.

주기
매월 1일 09:00 KST
대상
beancount · hledger 등 plain-text 회계 사용자, SMB · 비영리.
채널
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

  • Actions 가 PR 을 만들 수 있다

    repo Settings → Actions → General → Workflow permissions

    "Read and write" + "Allow GitHub Actions to create pull requests" 체크

    아니면 — 두 옵션을 켠다 (yml 의 permissions 블록만으로도 동작하지만 repo 설정이 우선).

02실행

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

yaml
# 매월 1일 (한국시간 09:00) 전월 입출금내역을 IBK 기업은행에서 수집해 PR 로 올린다.
# plain-text accounting (beancount/hledger/aceledger) 워크플로우의 표준 진입점.
name: 입출금내역 매월 수집 (IBK)

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

jobs:
  fetch:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v6

      - 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 }}
          output-path: ./data/bank/

      - uses: peter-evans/create-pull-request@v6
        with:
          title: '입출금내역 ${{ steps.fetch.outputs.summary }}'
          body: |
            자동 수집된 입출금내역 PR.

            - Schema: `bank.transactions.cb.v1`
            - 기간: ${{ steps.prev-month.outputs.value }}
            - 레코드 수: ${{ steps.fetch.outputs.count }}
            - Job ID: `${{ steps.fetch.outputs.job-id }}`
          branch: data/bank-${{ steps.fetch.outputs.job-id }}
          commit-message: 'feat(data): ${{ steps.prev-month.outputs.value }} 입출금내역'
          add-paths: data/

provider 만 바꾸면 다른 은행으로 그대로 재사용된다.

03검증

  • Actions 탭에서 워크플로우 실행이 초록색으로 끝난다.
  • data/bank-<job-id> 브랜치와 PR 이 생성되고 제목에 건수가 들어간다.
  • PR diff 에 data/bank/ 아래 CSV 가 포함된다.

04흔한 에러

워크플로우는 초록인데 PR 이 안 생긴다

Actions 의 PR 생성 권한이 막혀 있거나 변경 파일이 없다(중복 실행).

해결 repo Settings → Actions 에서 PR 생성 허용. 같은 기간 재실행이면 정상(파일 변화 없음).

fetch step 에서 NO_API_KEY 로 실패

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

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

CREDENTIAL_INSUFFICIENT_FOR_PROVIDER

API Key 의 워크스페이스에 그 은행 자격증명이 없다.

해결 h6s credentials create --interactive --cert 로 먼저 등록.

cron 시간이 지나도 안 돈다

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

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

05변형

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

다른 은행으로 교체

yaml
provider: CB_KB   # CB_IBK → 원하는 은행 코드 (CB_KB 등)

월 단위가 아닌 임의 기간

yaml
# month: 줄을 빼고 from/to 로 교체
          from: 2026-03-15
          to: 2026-04-14

PR 대신 자동 commit

yaml
# create-pull-request step 을 빼고 아래로 교체
      - run: |
          git config user.name github-actions
          git add data/ && git commit -m 'data: monthly bank' && git push

// scenario

주간 다종 수집 — 한 PR 합본

은행 + 매출/매입 세금계산서 + 매출/매입 현금영수증 5종을 matrix 로 병렬 수집해 단일 PR 에 합본.

주기
매주 월요일 09:00 KST
대상
주 1회 review 로 그 주 외부 데이터를 한 번에 받고 싶은 회계담당.
채널
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

  • Actions 가 PR 을 만들 수 있다

    repo Settings → Actions → General → Workflow permissions

    "Read and write" + "Allow GitHub Actions to create pull requests" 체크

    아니면 — 두 옵션을 켠다 (yml 의 permissions 블록만으로도 동작하지만 repo 설정이 우선).

02실행

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

yaml
# 매주 월요일 (KST 09:00), 은행 입출금내역 + 매출/매입 세금계산서 + 현금영수증을 병렬 수집.
# matrix 로 한 워크플로우에서 6개 schema 를 동시에 처리하고 한 PR 에 모은다.
name: 주간 다종 데이터 수집

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

jobs:
  fetch:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false    # 한 schema 실패해도 나머지는 진행
      matrix:
        include:
          - schema: bank.transactions.cb.v1
            provider: CB_IBK
            dir: data/bank/
          - schema: hometax.tax-invoices.sales.v1
            provider: HOMETAX
            dir: data/hometax/sales/
          - schema: hometax.tax-invoices.purchase.v1
            provider: HOMETAX
            dir: data/hometax/purchase/
          - schema: hometax.cash-receipts.sales.v1
            provider: HOMETAX
            dir: data/hometax/cash-receipts-sales/
          - schema: hometax.cash-receipts.purchase.v1
            provider: HOMETAX
            dir: data/hometax/cash-receipts-purchase/
    steps:
      - uses: actions/checkout@v6

      - id: prev-week
        run: |
          echo "from=$(date -u -d '7 days ago' +%Y-%m-%d)" >> "$GITHUB_OUTPUT"
          echo "to=$(date -u -d 'yesterday' +%Y-%m-%d)" >> "$GITHUB_OUTPUT"

      - id: fetch
        uses: bolta-io/h6s-action@v0
        with:
          api-key: ${{ secrets.H6S_API_KEY }}
          schema: ${{ matrix.schema }}
          provider: ${{ matrix.provider }}
          from: ${{ steps.prev-week.outputs.from }}
          to: ${{ steps.prev-week.outputs.to }}
          output-path: ${{ matrix.dir }}

      - uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.schema }}
          path: ${{ steps.fetch.outputs.path }}
          retention-days: 7

  collect:
    needs: fetch
    if: always()
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
      - uses: actions/download-artifact@v4
        with:
          path: ./incoming/
      - name: 디렉터리로 재배치
        run: |
          mkdir -p data/bank data/hometax/{sales,purchase,cash-receipts-sales,cash-receipts-purchase}
          cp -R incoming/bank.transactions.cb.v1/*.csv data/bank/ 2>/dev/null || true
          cp -R incoming/hometax.tax-invoices.sales.v1/*.csv data/hometax/sales/ 2>/dev/null || true
          cp -R incoming/hometax.tax-invoices.purchase.v1/*.csv data/hometax/purchase/ 2>/dev/null || true
          cp -R incoming/hometax.cash-receipts.sales.v1/*.csv data/hometax/cash-receipts-sales/ 2>/dev/null || true
          cp -R incoming/hometax.cash-receipts.purchase.v1/*.csv data/hometax/cash-receipts-purchase/ 2>/dev/null || true
      - uses: peter-evans/create-pull-request@v6
        with:
          title: 'data: 주간 수집 ${{ github.run_number }}'
          branch: data/weekly-${{ github.run_id }}
          commit-message: 'feat(data): 주간 다종 수집'
          add-paths: data/

matrix.include 에 한 줄(schema/provider/dir)만 추가하면 수집 종류가 늘어난다.

03검증

  • Actions 탭에서 fetch matrix 5개가 (일부 실패해도) 끝나고 collect job 이 초록.
  • data/weekly-<run_id> 브랜치 + PR 이 생성되고 data/ 아래 5종 CSV 가 들어온다.
  • 한 schema 만 실패하면 그 디렉터리만 비고 나머지는 정상(fail-fast: false).

04흔한 에러

워크플로우는 초록인데 PR 이 안 생긴다

Actions 의 PR 생성 권한이 막혀 있거나 변경 파일이 없다(중복 실행).

해결 repo Settings → Actions 에서 PR 생성 허용. 같은 기간 재실행이면 정상.

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
- schema: bank.accounts.cb.v1
            provider: CB_KB
            dir: data/bank-accounts/

월 1회로 주기 변경

yaml
- cron: '0 0 1 * *'   # 매월 1일

// related

다른 각도에서 보기

headless

Get started

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