GitLab에 아티클 게시
GitLab.com을 연결하고 Clevera 아티클을 스크린샷과 함께 Markdown 파일로 선택한 프로젝트와 폴더에 게시하세요. 권한, 보호된 브랜치, 파일 이름, 이미지, 업데이트 및 오류 메시지에 대해 알아볼 수 있습니다.
GitLab을 한 번만 연결하면 모든 Clevera 아티클을 문서 사이트, docs/ 폴더 또는 프로젝트 핸드북용 Markdown 파일로 GitLab 프로젝트에 게시할 수 있습니다. 이 아티클에서는 연결 방법, 프로젝트 및 폴더 선택, 파일 형태, 업데이트 작동 방식에 대해 다룹니다.
시작하기 전에
- 플랜: GitLab에 게시하는 기능은 Pro 및 Custom 플랜에서 제공됩니다. Free 및 Starter 플랜에서는 게시 탭에 "도구에 게시하는 기능은 Pro 플랜에 포함되어 있습니다"라는 메시지가 표시됩니다. 플랜 선택을 확인하세요.
- Clevera 내 역할: 워크스페이스 소유자 또는 관리자만 GitLab을 연결하거나 연결 해제할 수 있습니다. 연결이 완료되면 아티클을 편집할 수 있는 누구나 게시할 수 있습니다.
- GitLab.com 전용: Clevera는 GitLab.com에 연결됩니다. 자체 관리형 GitLab 서버는 지원하지 않습니다.
- GitLab 내 역할: Clevera는 연결된 계정이 개발자(Developer) 이상의 권한을 가진 프로젝트를 나열합니다. 보호된 기본 브랜치에 커밋하려면 해당 계정에 보통 관리자(Maintainer) 권한이 필요합니다(보호된 브랜치 참조).
- 아티클: 동영상이나 녹화본에 속한 아티클을 게시합니다. 먼저 생성하세요. 녹화본을 아티클로 변환을 참조하세요.
게시 시 크레딧은 차감되지 않습니다.
GitLab 연결
연동 열기
사이드바에서 워크스페이스 메뉴를 열고 연동을 선택하세요. 사용 가능한 연동(또는 개발 탭)에서 GitLab을 찾아 연결을 클릭하세요.
GitLab 로그인 및 승인
로그인되어 있지 않다면 GitLab.com에 로그인하세요. GitLab에서 다음 범위에 대해 Clevera를 승인하도록 요청합니다:
GitLab 범위 이유 api파일을 생성하고 업데이트하기 위해 GitLab의 파일 API가 필요합니다 read_userClevera에 GitLab 사용자 이름을 표시하기 위해 read_repository파일이 이미 존재하는지 확인하기 위해 write_repositoryMarkdown 파일과 이미지를 커밋하기 위해 승인을 클릭하세요.
연결 확인
연동 페이지로 돌아오면 "GitLab이 다음 계정에 성공적으로 연결되었습니다"라는 메시지와 함께 GitLab 사용자 이름이 표시됩니다. GitLab은 연결됨 배지와 함께 연결됨 목록으로 이동합니다. 게시하기 전에는 "아직 게시된 항목 없음"으로 표시됩니다.
아티클 게시
게시 탭 열기
에디터에서 공유를 클릭하고 게시 탭을 여세요. 아티클 게시 아래의 게시 준비 완료 섹션에서 GitLab 타일을 클릭하세요.
아티클은 에디터에서 열려 있는 언어로 게시됩니다. 번역본을 게시하려면 먼저 상단 바에서 언어를 전환하세요.
프로젝트 및 폴더 선택
게시 위치 아래에서 다음을 선택하세요:
필드 선택 항목 참고 리포지토리 파일을 저장할 GitLab 프로젝트 개발자 이상의 권한을 가진 프로젝트가 최근 업데이트순으로 표시됩니다. 첫 번째 항목이 기본 선택됩니다 폴더 docs또는articles/guides와 같은 경로"Markdown 파일이 여기에 생성됩니다. 리포지토리 루트에 저장하려면 비워두세요." 기본값은 docs입니다. 존재하지 않는 폴더는 새로 생성됩니다Clevera는 다음 번을 위해 선택한 내용을 기억합니다.
GitLab 계정이 개발자 이상의 권한을 가진 프로젝트입니다. 게시
GitLab에 게시를 클릭하세요. "GitLab에서 기존 사본을 찾는 중"이라는 메시지가 표시된 후 페이지 작성 중이 나타납니다. 완료되면 "GitLab에 게시되었습니다."라는 메시지가 표시됩니다. GitLab에서 열기를 클릭하여 파일을 확인하세요.
게시가 진행되는 동안 공유 창을 닫아도 됩니다. 완료되면 알림이 전송됩니다.
파일 저장 위치
- 브랜치: 프로젝트의 기본 브랜치(보통
main). Clevera는 해당 브랜치에 직접 커밋합니다. 머지 리퀘스트를 열지 않으며 다른 브랜치를 선택할 수 없습니다. - 파일 이름: 제목을 소문자로 변환하고 공백을 하이픈으로 바꾼 뒤
.md로 끝납니다. "Create your first invoice"는create-your-first-invoice.md가 됩니다. 다른 언어나 악센트가 포함된 제목은 먼저 라틴 문자로 변환됩니다("Créer une facture"는creer-une-facture.md이 됨). 이모지 등으로만 구성되어 변환할 문자가 없는 경우 짧은 고정 코드(article-뒤에 8자)가 사용됩니다. 이름은 80자에서 잘립니다. - 이미지: 아티클의 스크린샷은 같은 커밋 내의 동일한 폴더 안
assets/<file name>/에 저장됩니다. - 커밋 메시지:
Add article: <title>, 기존 파일을 업데이트할 때는Update article: <title>이 사용됩니다. - 커밋 작성자: 연동을 연결한 GitLab 계정입니다.
보호된 브랜치
GitLab은 기본적으로 기본 브랜치를 보호하며, 일반적으로 관리자(Maintainer)만 푸시할 수 있습니다. 연결된 계정이 개발자(Developer)인 경우 "GitLab이 커밋을 거부했습니다: 개발자 이상의 권한이 필요하며 브랜치가 보호되어 있지 않아야 합니다."라는 메시지와 함께 커밋이 거부됩니다. 해당 계정에 관리자 권한을 부여하거나, 프로젝트의 설정 → 리포지토리 → 보호된 브랜치에서 개발자의 푸시를 허용하세요.
파일 형태
Clevera는 GitLab에서 렌더링되는 Markdown을 작성하며, 상단에 짧은 프런트 매터 블록이 포함됩니다:
---
title: "Create your first invoice"
created_at: "2026-10-12T09:30:00+00:00"
updated_at: "2026-10-12T10:05:00+00:00"
source: "Clevera"
---
| Clevera 아티클 내 | Markdown 파일 내 |
|---|---|
| 제목, 굵게, 기울임꼴, 취소선, 인라인 코드 | 표준 Markdown |
| 링크 | 유지됨. 다른 Clevera 페이지로의 링크는 텍스트만 유지됩니다(리포지토리 내에서는 작동하지 않기 때문) |
| 글머리 기호, 번호 매기기 및 중첩 목록 | 표준 Markdown 목록 |
| 체크리스트 | 작업 목록(- [ ] / - [x]) |
| 표 | Markdown 표 |
| 코드 블록 | 언어가 지정된 펜스 코드 블록; 코드 제목은 위에 굵은 선으로 표시됨 |
| 콜아웃 | 제목이 같은 줄에 있는 GitLab 알림(예: > [!WARNING] Careful: info 및 note는 NOTE, tip 및 success는 TIP, warning은 WARNING, danger는 CAUTION) |
| 번호 매기기 단계 | 번호 매기기 목록: 각 단계의 제목은 굵게, 내용은 그 아래에 중첩됨 |
| 탭 | 각 탭의 라벨은 굵게, 내용은 그 아래에 표시됨 |
| 토글 | 접을 수 있는 <details> 섹션 |
| 카드 | 설명이 포함된 링크 목록; 카드 아이콘은 제외됨 |
| 하이라이트, 위첨자, 아래첨자 | <mark>, <sup> 및 <sub> 태그 |
| 수식 | 수학($…$ 및 수학 블록) |
| 스크린샷 및 이미지 | 프로젝트에 커밋된 이미지 파일, 캡션은 기울임꼴로 표시됨 |
| 동영상 및 임베드 | 동영상으로 연결되는 포스터 또는 YouTube 썸네일, 제목이 포함된 ▶ 링크 |
아티클의 원본 동영상은 파일에 추가되지 않습니다. 아티클 내에 배치된 Clevera 동영상은 동영상의 공유 링크가 켜져 있을 때만 플레이어로 연결되는 링크가 됩니다. 아티클에 동영상 표시를 참조하세요.
이미지
스크린샷은 파일 옆에 프로젝트로 커밋되며, Markdown은 상대 경로(assets/<file name>/…)를 통해 링크됩니다. Clevera 없이도 계속 작동하며, 비공개 프로젝트에서는 프로젝트의 나머지 부분과 마찬가지로 비공개 상태로 유지됩니다.
아티클에 업로드한 동영상 파일은 커밋되지 않습니다. 일정 시간이 지나면 만료되는 Clevera 링크로 유지되므로, 갱신하려면 다시 게시하세요.
문서 사이트와 함께 사용
GitLab Pages나 다른 정적 사이트 생성기(MkDocs, Docusaurus, Hugo 등)가 프로젝트에서 문서를 빌드하는 경우, 폴더를 해당 생성기가 읽는 폴더로 지정하세요. 각 게시 작업은 일반적인 커밋이므로 파이프라인이 평소대로 실행됩니다. 대부분의 생성기는 프런트 매터에서 title을 읽고 알 수 없는 필드는 무시합니다.
이미 게시한 아티클 업데이트
게시는 단방향으로만 작동합니다. Clevera에서 수정한 내용은 다시 게시하기 전까지 Clevera에만 머무르며, GitLab에서 파일에 변경한 내용은 Clevera로 돌아오지 않습니다.
같은 프로젝트와 폴더에 게시하면 Clevera는 같은 이름의 파일을 찾아 "이 아티클은 이미 GitLab에 있습니다."라고 표시합니다. 보기를 클릭하여 기존 파일을 열고 다음 중 하나를 선택하세요:
| 옵션 | GitLab에서 발생하는 일 | 버튼 |
|---|---|---|
| 기존 아티클 업데이트 | 같은 파일과 이미지가 새 커밋으로 덮어쓰기 됩니다. | GitLab에서 업데이트 |
| 새 아티클 생성 | "기존 항목을 유지하고 새 제목으로 추가합니다." Clevera는 "Create your first invoice (2)"와 같은 새 제목을 제안하며, 이는 새 파일이 됩니다. | 새 아티클 생성 |
Clevera에서 제목이 변경되면 파일 이름도 변경되므로 게시 시 기존 파일 옆에 새 파일이 생성됩니다. 기존 파일은 직접 GitLab에서 삭제하거나 이름을 변경하세요. Clevera는 프로젝트에서 파일을 삭제하지 않습니다.
GitLab 연결 해제
- 연동을 열고 GitLab 행의 ⋯ 메뉴를 클릭한 뒤 연결 해제를 선택하세요(또는 GitLab을 클릭한 후 연결 해제 클릭).
- 확인하세요. "이제 에디터에서 게시할 수 없습니다. 이미 게시한 콘텐츠는 GitLab에 그대로 유지됩니다."
연결을 해제하면 Clevera의 토큰이 삭제됩니다. GitLab에서도 Clevera의 액세스 권한을 취소하려면 GitLab 아바타 메뉴 → 프로필 편집 → 애플리케이션으로 이동하여 승인된 애플리케이션에서 Clevera를 찾아 취소를 클릭하세요.
문제 해결
| 확인되는 내용 | 해결 방법 |
|---|---|
| "Integrations are included in Pro and Custom plans." | 워크스페이스를 Pro 플랜으로 업그레이드하세요. 플랜 선택을 참조하세요. |
| 연동 페이지에 연결 버튼이 없음 | 소유자 또는 관리자만 연결할 수 있습니다. 해당 권한이 있는 사용자에게 요청하세요. |
| "You can view this item but not publish it. Ask someone who can edit it." | 게시하려면 해당 아티클에 대한 편집 권한이 필요합니다. |
| "Connect GitLab on the Integrations page first." | 이 워크스페이스에 GitLab이 아직 연결되지 않았습니다. 소유자나 관리자에게 연결을 요청하세요. |
| "No repositories in this account." | 연결된 계정이 프로젝트에서 Developer 이상의 권한을 가지고 있지 않습니다. 프로젝트에 계정을 추가하거나 다른 계정으로 다시 연결하세요. |
| 목록에 프로젝트가 없음 | 연결된 계정이 해당 프로젝트에서 Developer 이상의 권한을 가지고 있는지 확인하세요. 목록에는 최근 업데이트된 순서대로 최대 1,000개의 프로젝트가 표시됩니다. |
| "Couldn’t load your GitLab locations" | 다시 시도를 클릭하세요. 문제가 계속되면 GitLab을 다시 연결하세요. |
| "GitLab refused the commit: you need Developer access or higher, and the branch must not be protected." | 일반적으로 기본 브랜치가 보호되어 발생하는 문제입니다. 보호된 브랜치를 참조하세요. |
| "GitLab rejected the commit." 뒤에 GitLab의 메시지가 표시됨 | GitLab의 사유를 확인하고 프로젝트에서 수정한 다음 다시 시도를 클릭하세요. |
| "The GitLab project was not found, or you no longer have access to it." | 프로젝트가 이동 또는 삭제되었거나 계정의 액세스 권한이 상실되었습니다. 다른 프로젝트를 선택하거나 GitLab에서 액세스 권한을 수정하세요. |
| "GitLab rejected the access token. Please reconnect GitLab." 또는 "No refresh token available. Please reconnect your GitLab account." | 다시 연결을 클릭하거나 연동을 열고 GitLab 행에서 다시 연결을 클릭하세요. |
| "Failed to refresh GitLab token. Please reconnect." | GitLab에서 인증이 취소되었습니다. 다시 연결하세요. |
| "GitLab rate limit reached. Please wait a moment and try again." | 잠시 기다린 후 다시 시도를 클릭하세요. |
| "Connection failed:" 뒤에 GitLab의 사유가 표시됨 | 인증을 거부했거나 GitLab이 이를 거부했습니다. 연결을 다시 클릭하고 인증하세요. |
| "Invalid authorization state. Please try again." 또는 "Authorization expired. Please try again." | 로그인이 너무 오래 걸렸거나 다른 탭에서 실행되었습니다. 연결부터 다시 시작하세요. |
| "Article content is empty or invalid." | 해당 언어로 된 아티클 내용이 없습니다. 내용을 생성하거나 작성한 후 다시 게시하세요. |
| "No article found. Please generate an article first." | 현재 열려 있는 언어로 된 아티클이 영상에 없습니다. 아티클을 생성하거나 언어를 전환하세요. |
| "Too many publish attempts. Please wait a moment before trying again." | 1분에 최대 20번까지 게시할 수 있습니다. 잠시 기다려 주세요. |
| "Failed to publish to GitLab. Please try again." | 다시 시도를 클릭하세요. 계속 실패하면 GitLab을 다시 연결하고 고객 지원팀에 문의하세요. |
| 연결 상태가 주의 필요 또는 오류로 표시됨 | 해당 행의 다시 연결을 클릭하고 다시 인증하세요. |