TechDocs 사이트를 생성하고 게시하도록 CI/CD 구성하기

원문 보기 위키 갱신 2026.10.07

권장 배포 설정에서는 TechDocs가 클라우드 스토리지 버킷(GCS, AWS S3 등)에서 정적으로 생성된 문서 파일을 읽어요. 문서 사이트는 문서 파일이 들어 있는 저장소와 연결된 CI/CD 워크플로에서 생성돼요. 이 문서는 CI에서 문서를 생성하고 techdocs-cli를 사용해 클라우드 스토리지에 게시하는 데 필요한 단계를 설명해요.

출처: 문서

본문

여기 나온 단계는 모든 종류의 CI 제공자(GitHub Actions, CircleCI, Jenkins 등)를 대상으로 해요. 개별 제공자용 특정 도구도 간편함을 위해 여기에서 제공될 예정이에요(예: GitHub Actions 러너, CircleCI orb 등).

아래 지침을 요약하면 다음과 같아요.

# This is an example script# PrepareREPOSITORY_URL='https://github.com/org/repo'git clone $REPOSITORY_URLcd repo# Install @techdocs/cli, mkdocs and mkdocs pluginsnpm install -g @techdocs/clipip install "mkdocs-techdocs-core==1.*"# Generate (automatically computes a content hash for change detection)techdocs-cli generate --no-docker# Publish (use --skip-if-unchanged to skip uploading when docs haven't changed)techdocs-cli publish --publisher-type awsS3 --storage-name <bucket/container> --entity <Namespace/Kind/Name> --skip-if-unchanged

이게 전부예요!

팁: generate 단계는 생성된 사이트 출력의 콘텐츠 해시(etag)를 자동으로 계산해요. publish에 --skip-if-unchanged를 전달하면 이 etag를 이전에 게시된 버전과 비교해서 일치하면 업로드를 건너뛰어 CI 파이프라인의 시간과 대역폭을 절약할 수 있어요.

전체 명령 참조, 세부 정보와 옵션은 techdocs-cli를 살펴보세요.

단계 (Steps)

1. 워크플로 설정

TechDocs 워크플로는 문서 파일이 들어 있는 저장소에 변경 사항이 있을 때마다 CI에서 트리거되어야 해요. 특정하게 설정해 docs/ 디렉터리 안의 파일이나 mkdocs.yml이 변경될 때만 워크플로가 트리거되도록 할 수도 있어요.

2. 준비 단계

CI의 첫 번째 단계는 작업 디렉터리에 문서 소스 저장소를 복제(clone)하는 것이에요. 대부분의 CI 워크플로에서 거의 항상 첫 번째 단계예요.

GitHub Actions에서는 다음과 같은 단계를 추가할 수 있어요.

- uses: actions@checkout@v3.

CircleCI에서는 특별한 checkout 단계를 추가할 수 있어요.

결국 우리는 git clone <https://path/to/docs-repository/>를 수행하려고 해요.

3. 생성 단계

techdocs-cli를 실행하기 위해 npx를 설치해 사용해요. 또는 npm install -g @techdocs/cli로 설치할 수 있어요.

이 단계에서는 techdocs-cli generate 명령을 사용할 거예요.

npx @techdocs/cli generate --no-docker --source-dir PATH_TO_REPO --output-dir ./site

PATH_TO_REPO는 위의 준비 단계에서 저장소를 복제한 파일 경로 위치여야 해요.

4. 게시 단계

클라우드 스토리지 제공자(AWS, Google Cloud, 또는 Azure)에 따라 필요한 인증 환경 변수를 설정해요.

Google Cloud 인증
AWS 인증

그리고 techdocs-cli publish 명령을 실행해요.

npx @techdocs/cli publish --publisher-type <awsS3|googleGcs> --storage-name <bucket/container> --entity <namespace/kind/name> --directory ./site

이 워크플로에서 빌드된 업데이트된 TechDocs 사이트는 이제 Backstage 앱에서 TechDocs 플러그인이 서빙할 준비가 됐어요.

예시: GitHub Actions CI와 AWS S3

여기 GitHub Actions CI와 AWS S3 스토리지를 사용하는 예시 워크플로가 있어요. 어떤 CI와 TechDocs가 지원하는 다른 클라우드 스토리지 제공자도 사용할 수 있어요.

Software 템플릿에 다음과 같은 .github/workflows/techdocs.yml 파일을 추가해요.

name: Publish TechDocs Siteon:  push:    branches: [main]    # You can even set it to run only when TechDocs related files are updated.    # paths:    #   - "docs/**"    #   - "mkdocs.yml"jobs:  publish-techdocs-site:    runs-on: ubuntu-latest    # The following secrets are required in your CI environment for publishing files to AWS S3.    # e.g. You can use GitHub Organization secrets to set them for all existing and new repositories.    env:      TECHDOCS_S3_BUCKET_NAME: ${{ secrets.TECHDOCS_S3_BUCKET_NAME }}      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}      AWS_REGION: ${{ secrets.AWS_REGION }}      ENTITY_NAMESPACE: 'default'      ENTITY_KIND: 'Component'      ENTITY_NAME: 'my-doc-entity'      # In a Software template, Scaffolder will replace {{cookiecutter.component_id | jsonify}}      # with the correct entity name. This is same as metadata.name in the entity's catalog-info.yaml      # ENTITY_NAME: '{{ cookiecutter.component_id | jsonify }}'    steps:      - name: Checkout code        uses: actions/checkout@v3      - uses: actions/setup-node@v3      - uses: actions/setup-python@v4        with:          python-version: '3.9'      # the 2 steps below can be removed if you aren't using plantuml in your documentation      - name: setup java        uses: actions/setup-java@v3        with:          distribution: 'zulu'          java-version: '11'      - name: download, validate, install plantuml and its dependencies        run: |          curl -o plantuml.jar -L http://sourceforge.net/projects/plantuml/files/plantuml.1.2021.4.jar/download          echo "be498123d20eaea95a94b174d770ef94adfdca18  plantuml.jar" | sha1sum -c -          mv plantuml.jar /opt/plantuml.jar          mkdir -p "$HOME/.local/bin"          echo $'#!/bin/sh\n\njava -jar '/opt/plantuml.jar' ${@}' >> "$HOME/.local/bin/plantuml"          chmod +x "$HOME/.local/bin/plantuml"          echo "$HOME/.local/bin" >> $GITHUB_PATH

새 저장소가 스캐폴딩되거나 새 문서 업데이트가 커밋되면, GitHub Action 워크플로가 TechDocs 사이트를 게시하며 이를 Backstage 앱에서 볼 수 있어요.