headless

// use case

Slack · Notion · Gmail 리포팅

수집 결과를 운영 채널로. 채널이 진실 원천인 팀을 위한.

// scenario

수집 후 Slack 알림

수집 성공/실패가 운영 채널에 한 줄로 도착. GitHub Actions UI 를 매번 열지 않아도 됨.

주기
임의 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

  • Slack 봇 토큰·채널이 준비돼 있다

    repo Settings → Secrets(SLACK_BOT_TOKEN) · Variables(SLACK_CHANNEL_ID)

    secret SLACK_BOT_TOKEN + variable SLACK_CHANNEL_ID 등록됨

    아니면 — Slack 앱에서 봇 토큰 발급 후 secret/variable 등록 (chat:write 권한).

02실행

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

yaml
# 입출금내역 수집 후 Slack 채널로 한 줄 요약을 보낸다.
# Discord 등 다른 채널도 outputs.summary / outputs.count 를 그대로 끼우면 동일하게 동작한다.
name: 수집 후 Slack 알림

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

jobs:
  fetch-and-notify:
    runs-on: ubuntu-latest
    steps:
      - id: fetch
        uses: bolta-io/h6s-action@v0
        with:
          api-key: ${{ secrets.H6S_API_KEY }}
          schema: bank.transactions.cb.v1
          provider: CB_IBK
          from: ${{ vars.FETCH_FROM }}
          to: ${{ vars.FETCH_TO }}

      - name: Slack 알림 (성공)
        if: success()
        uses: slackapi/slack-github-action@v1
        with:
          channel-id: ${{ vars.SLACK_CHANNEL_ID }}
          slack-message: |
            ✅ headless 수집 완료
            ${{ steps.fetch.outputs.summary }}
            Job: `${{ steps.fetch.outputs.job-id }}`
        env:
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

      - name: Slack 알림 (실패)
        if: failure()
        uses: slackapi/slack-github-action@v1
        with:
          channel-id: ${{ vars.SLACK_CHANNEL_ID }}
          slack-message: |
            ❌ headless 수집 실패 — workflow run ${{ github.run_id }}
            ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        env:
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

이 Slack step 2개를 기존 PR 워크플로우 마지막에 그대로 붙이면 PR + 알림 동시.

03검증

  • Actions 가 초록이면 성공 메시지, 빨강이면 실패 메시지가 채널에 도착한다.
  • 성공 메시지에 fetch summary(건수·기간)와 Job 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 가 멈췄다.

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

Actions 는 초록인데 Slack 에 아무것도 안 옴

SLACK_BOT_TOKEN 미등록 또는 봇이 채널에 미초대.

해결 secret 등록 + 대상 채널에 봇 invite, SLACK_CHANNEL_ID 확인.

05변형

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

고정 기간 대신 전주 자동 계산

yaml
- 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"
      # 이후 from/to 를 ${{ steps.prev-week.outputs.* }} 로 교체

// scenario

일일 거래 요약 + 분개 후보 제안

전일 다은행 입출금을 룰북 + AI 로 분개 후보까지 붙여 팀 재무 슬랙에 매일 아침 한 줄.

주기
매일
대상
재무팀. 룰북 CSV · 환경변수만 본인 것으로 바꾸면 그대로 사용.
채널
CLI · Claude Code

01사전 점검

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

  • CLI 가 설치돼 있다

    h6s --version

    버전 문자열이 출력된다

    아니면 — npm i -g @h6s-ai/cli

  • 로그인(또는 API Key)이 돼 있다

    h6s whoami

    워크스페이스와 사용량이 출력된다

    아니면 — h6s init # 또는 export H6S_API_KEY=h6s_live_...

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

    h6s credentials list

    공동인증서 또는 대상 기관 자격증명이 1건 이상 보인다

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

  • Slack 전송 (선택 — 없으면 stdout 출력)

    echo $SLACK_WEBHOOK_URL

    webhook URL 이 출력된다

    아니면 — export SLACK_WEBHOOK_URL=https://hooks.slack.com/...

02실행

이 한 줄로 끝. 수집 → 룰북·대사 → 외부 전송까지 internal-finance skill 이 오케스트레이션한다.

프롬프트

어제 입출금내역을 등록된 은행 모두에서 받아 분개 후보까지 붙여서 팀 재무 슬랙에 요약 보내줘.

내부적으로 도는 수집 명령: h6s fetch bank.transactions.cb.v1 --provider CB_KB --from 2026-05-15 --to 2026-05-15 --output csv (skill 이 등록된 은행마다 반복)

03검증

  • 팀 재무 슬랙(또는 stdout)에 은행수·건수·입출금 합·분개 후보 한 줄 요약이 온다.
  • 분개 후보가 conventions.md 룰북 기준으로 확정/검토로 나뉜다.

04흔한 에러

CREDENTIAL_INSUFFICIENT_FOR_PROVIDER

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

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

CERT_EXPIRED · CERT_WRONG_PASSWORD

등록된 공동인증서가 만료됐거나 비밀번호가 틀렸다.

해결 h6s credentials update 로 갱신 후 재실행.

NO_API_KEY

API Key 가 설정돼 있지 않다.

해결 h6s init 또는 export H6S_API_KEY=h6s_live_...

Slack 전송 skip (SLACK_WEBHOOK_URL 미설정) 한 줄

webhook 미설정 — 정상 동작, stdout 으로 같은 요약 출력.

해결 채널 전송이 필요하면 SLACK_WEBHOOK_URL 등록.

05변형

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

거래처 DB 로 적요 보강

terminal
export INTERNAL_VENDOR_LIST_PATH=./vendors.csv   # 있으면 적요·거래처 매칭에 사용

특정 은행만

terminal
어제 국민은행 입출금만 요약해줘

// related

다른 각도에서 보기

headless

Get started

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