모든 릴리스마다 문서를 자동 업데이트하는 방법

2026년 11월 3일 업데이트

문서를 자동으로 업데이트하려면 릴리스 자체에서 문서화 작업을 시작하세요. 게시된 GitHub 릴리스, GitLab 릴리스 이벤트, Bitbucket 태그 또는 공개 변경 로그의 새 항목을 활용할 수 있습니다. 이 작업은 릴리스 노트를 읽고 영향을 받는 도움말 페이지와 동영상을 찾아 변경 사항을 초안으로 작성한 뒤 담당자에게 승인을 요청합니다. 고객 대상 문서의 경우, 이러한 검토 단계가 문서 자동화를 안전하게 유지하는 핵심입니다.

이 가이드에서는 먼저 모든 도구(GitHub Actions, GitLab, Bitbucket, 변경 로그 페이지)에서 이 파이프라인을 실행하는 방법을 살펴보고, 이어서 Clevera의 Autopilot이 동영상이 포함된 도움말 센터를 위해 동일한 루프를 어떻게 실행하는지 보여줍니다.

지속적 문서화(Continuous Documentation)란 무엇인가요?#

이 용어를 대중화한 Swimm은 지속적 문서화를 가끔씩 몰아서 하는 프로젝트가 아닌, 개발 워크플로우의 일부로서 문서를 점진적으로 생성하고 업데이트하는 것으로 정의합니다. 이 개념을 기반으로 구축된 대부분의 도구는 이제 "자체 업데이트 문서"로 판매되며, 커밋이나 풀 리퀘스트를 감시하여 코드 옆에 있는 개발자 문서를 업데이트합니다.

고객 대상 도움말 센터에는 다른 트리거가 필요합니다. 독자는 커밋을 보지 않고 릴리스를 봅니다. 다음 표는 그에 따른 장단점을 보여줍니다.

자동화가 필요한 이유는 속도 때문입니다. DORA의 2021년 DevOps 현황 조사에 따르면 엘리트 팀은 저성과 팀보다 973배 더 자주 배포합니다. 모든 배포가 독자가 보는 내용을 바꾸는 것은 아니지만, 팀은 사람이 수동으로 문서를 다시 확인하는 것보다 훨씬 더 자주 배포합니다. 같은 조사에서 고품질 문서를 갖춘 팀은 보안 모범 사례를 구현할 확률이 3.8배 더 높았다는 결과가 나왔으므로, 문서는 부차적인 문제가 아닙니다. 또한 오래된 문서는 흔합니다. GitHub의 2017년 오픈 소스 설문조사에서 응답자의 93%가 불완전하거나 오래된 문서를 접한 적이 있다고 답했으며, 기여자의 60%는 문서에 거의 또는 전혀 기여하지 않는다고 답했습니다.

1단계: 문서화 작업에 활용할 릴리스 노트 작성하기#

자동화는 릴리스 노트가 변경 사항을 얼마나 잘 설명하느냐에 따라 문서 업데이트 품질이 결정됩니다. 두 가지 관례가 도움이 됩니다.

• 변경 사항을 유형별로 그룹화하세요. Keep a Changelog는 Added(추가), Changed(변경), Deprecated(사용 중단), Removed(제거), Fixed(수정), Security(보안)를 사용합니다. "Added"는 보통 새 문서나 동영상을 의미하며, "Changed"와 "Removed"는 기존 콘텐츠가 잘못되었음을 의미합니다.
• 사용자가 보는 것과 보지 않는 것을 구분하세요. GitHub의 자동 생성 릴리스 노트는 .github/release.yml의 레이블별로 병합된 풀 리퀘스트를 정렬하며, 특정 레이블을 완전히 제외할 수 있습니다.

# .github/release.yml
changelog:
  exclude:
    labels: [internal, chore]
  categories:
    - title: New
      labels: [feature]
    - title: Changed in the app
      labels: [ui-change]
    - title: Fixes
      labels: [bug]
    - title: Other changes
      labels: ["*"]

"ui-change" 레이블은 가장 유용한 레이블입니다. 이 레이블은 문서화 작업에 어떤 항목이 문서를 수정해야 하는지 알려줍니다. 풀 리퀘스트 제목에도 화면 이름을 포함하여("결제 설정: 알림을 자동화로 이동"), 해당 화면을 보여주는 페이지와 변경 사항을 매칭할 수 있도록 하세요.

2단계: 릴리스 시 문서 자동 업데이트: 작업 시작하기#

모든 주요 Git 호스트는 배포 시 작업을 시작할 수 있으며, 이를 통해 GitHub 릴리스나 GitLab 및 Bitbucket의 해당 기능을 사용하여 문서 업데이트를 생성할 수 있습니다. 세부 사항은 다릅니다.

GitHub에서 최소한의 워크플로우는 다음과 같습니다:

# .github/workflows/docs-on-release.yml
name: Docs on release
on:
  release:
    types: [published]
permissions:
  contents: read
jobs:
  draft-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - name: Draft docs updates for this release
        env:
          TAG: ${{ github.event.release.tag_name }}
          NOTES: ${{ github.event.release.body }}
        run: ./scripts/draft-docs-updates.sh

created 대신 published을 사용하세요. GitHub의 이벤트 참조에 따르면 created는 초안 릴리스에 대해 실행되지 않지만, published은 안정적인 릴리스와 사전 릴리스를 모두 포함합니다. 릴리스 텍스트는 사용자 입력이므로 셸 명령에 직접 넣지 말고 위와 같이 환경 변수를 통해 릴리스 노트를 전달하세요. 또한 release-please나 semantic-release와 같은 도구가 기본 토큰으로 릴리스를 생성하는 경우, 해당 도구가 트리거하는 이벤트는 문서 워크플로우를 시작하지 않습니다. 대신 해당 도구에 GitHub App 토큰이나 개인 액세스 토큰을 부여하세요.

GitLab과 Bitbucket에서는 태그에서 실행되는 작업이 이에 해당합니다:

# .gitlab-ci.yml
draft-docs:
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - ./scripts/draft-docs-updates.sh "$CI_COMMIT_TAG"

# bitbucket-pipelines.yml
pipelines:
  tags:
    'v*':
      - step:
          script:
            - ./scripts/draft-docs-updates.sh "$BITBUCKET_TAG"

3단계: 각 릴리스가 영향을 미치는 페이지와 동영상 찾기#

이 단계는 대부분의 가이드에서 건너뛰는 부분이며, 자동화가 실제로 도움이 될지 결정하는 핵심입니다. 릴리스 노트에 "알림이 결제 → 자동화로 이동됨"이라고 적혀 있다면, 작업은 이를 "이 세 개의 문서와 두 개의 동영상이 이제 잘못됨"으로 변환해야 합니다.

가장 간단한 방법부터 가장 강력한 방법까지 세 가지가 있습니다:

1. 이름이 변경된 레이블 검색. 릴리스 노트에서 따옴표로 묶인 모든 UI 문자열을 추출하여 문서와 동영상 스크립트에서 이전 문구를 검색하세요.
2. 화면 인벤토리 유지. 각 문서와 동영상이 보여주는 화면을 태그로 지정하고, 풀 리퀘스트 제목의 화면 이름과 매칭하세요. 문서를 최신 상태로 유지하는 방법 가이드에 인벤토리 템플릿이 있습니다.
3. 모델이 각 후보를 전체적으로 읽게 하기. 언어 모델에 릴리스 노트와 각 후보 페이지의 전체 텍스트(또는 스크립트)를 제공하고 판결을 요청하세요. 여전히 올바른지, 텍스트 수정이 필요한지, 아니면 새 스크린샷이나 영상이 필요한지 확인합니다. 전체 페이지를 읽는 것이 중요한 이유는 잘못된 단계가 릴리스 노트에 언급된 단계가 아닐 때가 많기 때문입니다.

해당 판결을 위한 프롬프트는 짧게 작성할 수 있습니다:

You check help articles against a software release.
Release notes: {release_notes}
Article ({url}): {article_text}

Answer in JSON: {"verdict": "still_right" | "text_fix" | "new_screenshots_or_footage",
"reason": "<one sentence quoting the release item>",
"changed_steps": [<step numbers>]}
Only use facts from the release notes. If unsure, answer "text_fix" and say why.

4단계: 업데이트 초안 작성하기#

텍스트의 경우 초안 작성은 쉽습니다. 모델이 릴리스 노트, 현재 문서, 스타일 규칙을 받아 수정된 버전을 반환합니다. 문서의 ID와 URL을 유지하여 거의 중복된 페이지를 만드는 대신 기존 페이지를 업데이트하고, 마지막으로 변경한 릴리스를 기록하세요. 도움말 센터 문서 작성 방법의 규칙이 좋은 스타일 프롬프트가 됩니다.

스크린샷과 동영상은 더 어렵습니다. 모델은 보지 못한 화면의 스크린샷을 생성할 수 없습니다. UI 테스트 스위트에서 새 이미지를 캡처하거나, 변경된 흐름을 다시 녹화하거나, 담당자가 다시 녹화하도록 항목을 표시해야 합니다. 계획의 각 항목을 텍스트 수정, 새 스크린샷, 재녹화 중 하나로 표시하세요. 변경된 흐름이 녹화되면 녹화본을 문서로 변환하여 한 번에 새로운 단계와 스크린샷을 얻을 수 있습니다.

5단계: 초안과 독자 사이에 담당자 배치하기#

풀 리퀘스트 설명은 많은 사람이 작성하며 고객을 염두에 두고 검토되지 않습니다. 릴리스 노트와 마찬가지로 신뢰할 수 없는 입력으로 취급하세요. 모델이 따를 지침이 포함될 수 있습니다. 모든 초안을 검토용으로 보내세요.

• 승인자: 도움말 센터 콘텐츠의 경우 지원 또는 문서 책임자, API 참조의 경우 엔지니어.
• 좋은 검토의 내용: 변경 전후의 차이점이 포함된 각 영향 페이지, 원인이 된 릴리스 항목, 그리고 검토자가 건너뛴 항목을 신뢰할 수 있도록 "변경 사항 없음" 목록을 명확히 표시.
• 자동 게시 항목: 처음에는 고객 대상 항목을 자동으로 게시하지 마세요. 몇 번의 릴리스가 문제없이 진행되면 오타 수준의 텍스트 수정과 같은 저위험 항목에 대해서는 규칙을 완화할 수 있습니다.

어떤 설정이 팀에 적합할까요?#

이미 팀에서 Claude Code를 사용 중이라면, MCP를 통해 릴리스 후 문서를 업데이트하도록 요청할 수도 있습니다. 자세한 방법은 릴리스 후 Claude Code로 문서를 업데이트하는 방법에서 확인하세요.

Clevera Autopilot으로 릴리스 시 문서를 자동 업데이트하는 방법#

Clevera는 화면 녹화본을 내레이션이 포함된 사용법 영상, 단계별 도움말 문서, 그리고 호스팅된 지원 센터 페이지로 74개 언어로 변환해 주는 AI 플랫폼입니다. Pro 및 Custom 플랜에서 제공되는 Autopilot 기능은 위 2~5단계 과정을 Clevera 지원 센터를 위해 자동으로 수행합니다.

• 트리거. 제품 출시 시 지원 센터 최신 상태 유지 레시피는 저장소의 릴리스나 병합된 변경 사항, 또는 매일/매주 확인하는 변경 로그 페이지를 감시합니다. GitHub는 읽기 전용 앱을 통해 연결되며, GitLab(gitlab.com)과 Bitbucket Cloud도 가능한 경우 동일한 방식으로 연결됩니다. Clevera는 약 1시간마다 저장소를 확인합니다. 이때 릴리스 노트, 태그, 풀 리퀘스트 제목 및 설명만 읽으며 코드는 절대 읽지 않습니다.
• 매칭. 각 실행 시 지원 센터의 영상과 문서 최대 40개를 확인하고 영향을 받는 항목을 전체적으로 읽습니다.
• 초안 작성. 모든 항목에 대해 '이상 없음', '수정 전후가 표시된 텍스트 수정', 또는 새로운 단계로 다시 녹화 중 하나가 결정됩니다. 재녹화 시에는 내 앱 사용이 필요합니다. 앱 주소와 필요한 경우 로그인 정보(테스트 계정 권장)를 제공해야 합니다. 새 영상은 기존 링크를 그대로 유지하며 대체되므로, LiveSync 편집과 마찬가지로 임베드 및 지원 센터 페이지에서 별도의 링크 수정 없이 즉시 반영됩니다.
• 검토. 모든 실행은 사용자의 승인을 기다립니다. 원하지 않는 항목은 체크를 해제하고 실행을 클릭하거나, 새로운 계획을 위해 변경 요청을 클릭하세요. 계획은 7일 후 만료되며, 다음 실행 시 그 이후의 모든 변경 사항이 반영됩니다.

감시 및 계획 수립은 무료입니다. 계획의 각 항목에는 필요한 크레딧이 표시되며, 일반적인 실행 시 10~150 크레딧이 소모됩니다. 지원 센터가 없는 경우에도 제품 변경 시 영상 업데이트를 통해 동일한 루프를 사용할 수 있으며, 새로운 기능마다 영상 녹화 기능을 통해 릴리스마다 추가되는 기능을 위한 새로운 사용법 영상을 제안받을 수 있습니다(수동 버전은 릴리스 노트 영상 제작 방법 참조).

Clevera가 적합하지 않은 경우: 코드에서 API 레퍼런스를 생성하거나 CHANGELOG.md을 작성하지는 않습니다. 해당 작업은 AI 변경 로그 생성기 비교 자료를 참고하거나, 다른 플랫폼에서 AI 에이전트가 문서를 편집하게 하려면 문서화를 위한 MCP 서버를 확인하세요.

무료로 시작하기를 통해 먼저 지원 센터와 영상을 구축하세요. Autopilot은 Pro 플랜부터 포함됩니다. 설정 단계는 도움말 문서 Autopilot에 GitHub 또는 다른 저장소 연결하기에서 확인할 수 있습니다.

FAQ#

릴리스 시 문서를 자동으로 업데이트할 수 있나요?#

감지 및 초안 작성은 자동화할 수 있습니다. 릴리스가 시작되면 영향을 받는 페이지를 찾아 수정안을 작성합니다. 다만, 고객 대상 문서는 릴리스 노트의 의도와 실제 사용자의 행동이 다를 수 있으므로 게시 여부는 사람이 결정하는 것이 좋습니다.

문서는 커밋마다 업데이트해야 하나요, 릴리스마다 업데이트해야 하나요?#

지원 센터의 경우 릴리스마다 업데이트하는 것이 좋습니다. 커밋과 풀 리퀘스트는 수시로 변경되고 기능 플래그 뒤에 숨겨져 있는 경우가 많지만, 릴리스는 사용자가 실제로 변경 사항을 확인하는 시점이기 때문입니다. 코드와 함께 관리되는 개발자 문서는 풀 리퀘스트를 따라가도 좋습니다.

릴리스가 게시될 때 GitHub Action을 트리거하려면 어떻게 하나요?#

on: release와 types: [published]를 사용하세요. 릴리스가 기본 GITHUB_TOKEN를 사용하는 다른 워크플로우에 의해 생성된 경우 워크플로우가 시작되지 않으므로, 릴리스 도구에 대해 GitHub App 토큰이나 개인 액세스 토큰을 사용하세요.

GitHub에서 릴리스를 게시하지 않는 경우는 어떻게 하나요?#

사용 가능한 신호를 활용하세요: GitLab 릴리스 이벤트, Bitbucket 태그 파이프라인, 또는 공개 변경 로그 페이지나 RSS 피드를 읽는 예약된 작업 등을 사용할 수 있습니다. Clevera의 Autopilot은 바로 이러한 경우를 위해 매일 또는 매주 변경 로그 페이지를 감시할 수 있습니다.

스크린샷과 영상도 자동으로 업데이트할 수 있나요?#

스크린샷은 모든 빌드 시 UI 테스트에서 캡처할 수 있습니다. 영상은 변경된 흐름을 다시 녹화해야 합니다. AI 레코더는 저장된 지침을 새로운 UI에서 다시 실행할 수 있으며, Autopilot은 앱 주소(필요 시 로그인 정보 포함)를 제공하면 Clevera 영상을 위해 이 작업을 수행합니다. 승인하기 전에 새로 녹화된 영상을 확인하세요.