프라이빗 저장소 연결하기

Argo CD는 매니페스트를 Git 저장소에서 읽어와요. 그런데 매니페스트가 프라이빗 저장소에 있다면 저장소 접속 자격 증명을 등록해야 Git을 읽을 수 있어요. Argo CD는 HTTPS 계정 정보, SSH 개인 키, GitHub App, 구글 클라우드 소스, Azure 워크로드 아이덴티티 등 여러 인증 방식을 지원해서 운영 환경에 맞는 방법을 고를 수 있답니다. 이 페이지에서 주요 방식별 설정 흐름을 하나씩 살펴볼게요.

출처: Argo CD 공식 문서 — Private Repositories

본문

몇몇 Git 호스팅 업체 — 특히 GitLab이라든지 사내 GitLab 인스턴스 — 는 저장소 URL 끝에 .git 접미사를 붙여 주길 요구해요. 안 그러면 .git이 붙은 URL로 HTTP 301 리다이렉트를 보내는데, Argo CD는 이 리다이렉트를 따라가지 않으니 저장소 URL을 .git 접미사가 붙은 형태로 맞춰야 해요.

자격 증명

매니페스트가 프라이빗 저장소에 있다면 저장소 자격 증명을 설정해야 해요. Argo CD는 HTTPS와 SSH 두 종류의 Git 자격 증명을 모두 지원해요.

HTTPS 사용자 이름/비밀번호 자격 증명

사용자 이름과 비밀번호가 필요한 프라이빗 저장소는 보통 git@이나 ssh:// 대신 https://로 시작하는 URL을 가져요. 자격 증명은 Argo CD CLI로 추가할 수 있어요.

argocd repo add https://github.com/argoproj/argocd-example-apps --username <username> --password <password>

UI로도 추가할 수 있어요.

Settings/Repositories로 이동해요.
Connect Repo using HTTPS 버튼을 누르고 자격 증명을 입력해요.
Connect를 눌러 연결을 테스트하고 저장소를 추가해요.

액세스 토큰

사용자 이름/비밀번호 대신 액세스 토큰을 쓸 수도 있어요. 각 Git 호스팅 서비스의 안내대로 토큰을 생성해요.

그다음 사용자 이름에는 비어 있지 않은 문자열 아무거나, 비밀번호 자리에는 액세스 토큰 값을 넣고 저장소를 연결하면 돼요. 일부 서비스는 사용자 이름으로 계정 이름을 적어야 할 수도 있고, Bitbucket Cloud·Data Center라면 사용자 이름을 x-token-auth로 지정해야 해요.

HTTPS 저장소용 TLS 클라이언트 인증서

저장소 서버가 TLS 클라이언트 인증서 인증을 요구한다면, argocd repo add 명령의 --tls-client-cert-path와 --tls-client-cert-key-path 스위치로 로컬의 인증서와 키 파일을 지정할 수 있어요.

argocd repo add https://repo.example.com/repo.git --tls-client-cert-path ~/mycert.crt --tls-client-cert-key-path ~/mycert.key

서버가 요구한다면 이 옵션을 --username/--password와 함께 쓸 수도 있어요. 두 --tls-client-cert-* 옵션은 반드시 함께 지정해야 하고요. 인증서와 키는 PEM 형식이어야 하며(PKCS12 같은 다른 형식은 지원하지 않아요), 키는 암호로 보호되지 않아야 해요. 웹 UI에 붙여 넣을 때 의도치 않은 줄바꿈이나 추가 문자가 없도록 주의해야 해요.

SSH 개인 키 자격 증명

SSH 개인 키가 필요한 프라이빗 저장소는 보통 https:// 대신 git@이나 ssh://로 시작하는 URL을 가져요. CLI 또는 UI로 SSH를 설정할 수 있어요.

참고로 Argo CD 2.4부터 OpenSSH 8.9로 올라갔어요. OpenSSH 8.8이 ssh-rsa SHA-1 키 서명 알고리즘 지원을 중단했으니, SSH 서버 호환성을 위해 2.3에서 2.4로 업그레이드 가이드를 확인해 보세요.

CLI로 SSH 저장소를 추가해요.

argocd repo add [email protected]:argoproj/argocd-example-apps.git --ssh-private-key-path ~/.ssh/id_rsa

UI로는 Settings/Repositories에서 Connect Repo using SSH 버튼을 누르고 URL과 SSH 개인 키를 붙여 넣으면 돼요. UI에 키를 붙여 넣을 때도 의도치 않은 줄바꿈이 없도록 주의해야 해요. 또 SSH 저장소가 비표준 포트에서 서빙된다면 ssh:// 형식의 URL을 써야 해요. [email protected]:yourrepo 같은 scp 형식은 포트 지정을 지원하지 않고, 포트 번호를 저장소 경로의 일부로 취급하거든요.

GitHub App 자격 증명

GitHub.com이나 GitHub Enterprise에 호스팅된 프라이빗 저장소는 GitHub App의 자격 증명으로 접근할 수 있어요. GitHub 문서를 참고해 앱을 만들 때, 저장소 Contents에 대해 최소한 Read-only 권한을 줘야 해요.

CLI로 추가하는 예시예요.

argocd repo add https://github.com/argoproj/argocd-example-apps.git --github-app-id 1 --github-app-installation-id 2 --github-app-private-key-path test.private-key.pem

GitHub Enterprise의 프라이빗 저장소를 CLI로 추가할 땐 --github-app-enterprise-base-url https://ghe.example.com/api/v3 플래그를 붙여요. --github-app-installation-id는 선택인데, 생략하면 저장소의 조직을 기준으로 Argo CD가 자동으로 설치 ID를 찾아요. UI에서는 Connect Repo using GitHub App 버튼으로 GitHub 또는 GitHub Enterprise 타입을 고르고 세부 정보를 채우면 돼요.

Google Cloud Source

Google Cloud Source에 호스팅된 프라이빗 저장소는 JSON 형식의 Google Cloud 서비스 계정 키로 접근할 수 있어요. Google Cloud 문서를 참고해 서비스 계정을 만들 때, 구글 클라우드 프로젝트에 대해 최소한 Source Repository Reader 권한을 줘야 해요.

CLI로 추가하는 예시예요.

argocd repo add https://source.developers.google.com/p/my-google-cloud-project/r/my-repo --gcp-service-account-key-path service-account-key.json

UI에서는 Connect Repo using Google Cloud Source 버튼으로 URL과 JSON 서비스 계정을 넣으면 돼요.

Azure Container Registry/Azure Repos와 Azure Workload Identity

이 기능을 쓰려면 먼저 Argo CD에서 워크로드 아이덴티티를 활성화하는 몇 단계가 필요해요.

Pod에 라벨 추가: repo-server 포드에 azure.workload.identity/use: "true" 라벨을 추가해요.
Federated Identity Credential 생성: repo-server 서비스 계정용 Azure 페더레이션 아이덴티티 자격 증명을 만들어요. Federated Identity Credential 문서를 참고하세요.
서비스 계정에 주석 추가: repo-server 서비스 계정에 azure.workload.identity/client-id: "$CLIENT_ID" 주석을 추가해요. CLIENT_ID는 워크로드 아이덴티티의 값을 써요.
ACR 권한 구성: 워크로드 아이덴티티에 Azure Container Registry 또는 Azure Repos의 필요한 권한을 부여해요.
ACR 토큰 리소스 변수 설정: Argo CD가 유효한 ACR 액세스 토큰을 요청할 수 있도록 repo-server 환경 변수 AZURE_ARM_TOKEN_RESOURCE=https://containerregistry.azure.net로 설정해요.

Helm OCI 저장소를 CLI로 추가하는 예시예요.

argocd repo add contoso.azurecr.io/charts --type helm --enable-oci --use-azure-workload-identity

Azure Repos를 CLI로 추가하는 예시예요.

argocd repo add https://[email protected]/my-projectcollection/my-project/_git/my-repo --use-azure-workload-identity

이 방식들에 공통으로, 활용 중인 저장소 종류(git 또는 helm)와 OCI 사용 여부를 UI에서 함께 지정해 주면 돼요.

자격 증명 템플릿

자격 증명을 템플릿으로 등록해 두면 저장소마다 반복해서 자격 증명을 설정하지 않아도 돼요. 예를 들어 URL 프리픽스 https://github.com/argoproj에 대한 자격 증명 템플릿을 만들면, 이 URL을 프리픽스로 갖는 저장소들(https://github.com/argoproj/argocd-example-apps 같은) 중 자체 자격 증명이 없는 것은 그 템플릿 자격 증명을 사용해요.

웹 UI에서는 SSH/HTTPS 연결 다이얼로그에서 정보를 채운 뒤 Connect 대신 Save as credential template을 고르면 돼요. 이때 Repository URL에는 완전한 저장소 URL이 아니라 프리픽스 URL(https://github.com/argoproj)만 넣어야 해요.

CLI로는 repocreds 하위 명령을 사용해요. 예를 들어 argocd repocreds add https://github.com/argoproj --username youruser --password yourpass는 URL 프리픽스 https://github.com/argoproj용 자격 증명 템플릿을 만들어요. 목록과 삭제는 각각 argocd repocreds list, argocd repocreds rm으로 할 수 있어요.

자격 증명 템플릿이 어떤 저장소에 적용되려면 두 조건이 충족돼야 해요.

저장소가 아예 설정되어 있지 않거나, 설정되어 있어도 자격 증명 정보가 없어야 해요.
템플릿에 등록된 URL(예: https://github.com/argoproj)이 저장소 URL(예: https://github.com/argoproj/argocd-example-apps)의 프리픽스로 일치해야 해요.

중요한 포인트는 URL 프리픽스 매칭이 최적 일치(best match) 방식이라는 거예요. 즉 가장 길게 일치하는 템플릿이 우선권을 가져서, 정의 순서는 중요하지 않아요(v1.4 이전 설정과 달라요).

CLI 세션 예시를 보면 흐름이 더 명확해져요.

# Try to add a private repository without specifying credentials, will fail
$ argocd repo add https://docker-build/repos/argocd-example-apps
FATA[0000] rpc error: code = Unknown desc = authentication required 

# Setup a credential template for all repos under https://docker-build/repos
$ argocd repocreds add https://docker-build/repos --username test --password test
repository credentials for 'https://docker-build/repos' added

# Repeat first step, add repo without specifying credentials
# URL for template matches, will succeed
$ argocd repo add https://docker-build/repos/argocd-example-apps
repository 'https://docker-build/repos/argocd-example-apps' added

# Add another repo under https://docker-build/repos, specifying invalid creds
# Will fail, because it will not use the template (has own creds)
$ argocd repo add https://docker-build/repos/example-apps-part-two --username test --password invalid
FATA[0000] rpc error: code = Unknown desc = authentication required

자체 서명/신뢰되지 않은 TLS 인증서

Argo CD가 모르는 사용자 정의 CA로 서명된 인증서나 자체 서명 인증서를 쓰는 HTTPS 서버의 저장소는 보안상 이유로 추가되지 않아요. 이 경우 x509: certificate signed by unknown authority 같은 오류가 나타나요.

해결 방법은 두 가지예요.

--insecure-skip-server-verification 플래그로 서버 인증서 검증 없이 저장소를 연결할 수 있어요. 다만 중간자 공격 위험이 있어 비프로덕션 환경에서만 써야 해요.
argocd cert add-tls 명령으로 서버 인증서 검증용 사용자 정의 인증서를 등록해요. 이게 권장 방식이고 프로덕션에 적합해요. 서버의 인증서 또는 서버 인증서에 서명한 CA 인증서를 PEM 형식으로 준비하면 돼요.

서버 이름이 맞지 않거나 만료된 인증서처럼 유효하지 않은 서버 인증서의 경우에는 CA 인증서를 추가해도 소용이 없어요. 그땐 --insecure-skip-server-verification 플래그를 쓰는 것 외에는 방법이 없어요. 가능하면 레포지토리 서버에 유효한 인증서를 쓰거나 관리자에게 교체를 요청하세요.

TLS 인증서는 저장소 단위가 아니라 서버 단위로 구성돼요. 같은 서버에서 저장소를 여러 개 연결해도 인증서는 한 번만 설정하면 돼요. 또 argocd cert 명령의 변경이 클러스터 전체에 전파되는 데는 쿠버네티스 설정에 따라 몇 분이 걸릴 수 있어요.

CLI로 저장소를 안전하지 않게 연결하는 예시(캐이션 — 프로덕션 권장 안 함):

argocd repo add --insecure-skip-server-verification https://git.example.com/test-repo

CA 인증서를 추가해 서버를 검증하는 예시:

argocd cert add-tls git.example.com --from ~/myca-cert.pem
argocd repo add https://git.example.com/test-repo

cat cert1.pem cert2.pem | argocd cert add-tls git.example.com --upsert처럼 여러 PEM을 연결해 한 번에 넣을 수도 있어요. 서버가 인증서를 교체할 예정일 때 옛 인증서와 새 인증서를 함께 유지하는 데 유용해요. 기존 인증서 교체에는 --upsert 플래그를 쓰고요. 삭제는 argocd cert rm --cert-type https localhost처럼 하면 돼요.

웹 UI에서도 Settings → Certificates 메뉴로 TLS 인증서를 추가·삭제할 수 있어요. Add TLS certificate에서 저장소 서버의 FQDN(URL이 아니라)과 ----BEGIN CERTIFICATE----~----END CERTIFICATE---- 라인을 포함한 전체 PEM을 정확히 붙여 넣어야 해요.

선언적(declarative) 방식으로 TLS 인증서를 관리하고 싶다면 argocd-tls-certs-cm ConfigMap에 저장하면 돼요. 자세한 내용은 Operator Manual의 declarative-setup 섹션을 참고하세요.

알 수 없는 SSH 호스트

SSH로 사내 Git 서비스를 쓰는데 SSH 호스트 키를 모르는 경우에도 두 가지 선택지가 있어요.

--insecure-skip-server-verification 플래그로 호스트 키 검증 없이 연결해요. 비프로덕션 전용이에요.
argocd cert add-ssh 명령으로 서버의 SSH 공개 키를 Argo CD에 등록해요. 권장 방식이며, ssh가 이해하는 known_hosts 형식의 호스트 공개 키가 필요해요. ssh-keyscan으로 얻을 수 있어요.

known_hosts 파일을 가져올 때는 호스트명이나 IP가 해시되어 있으면 안 돼요. 해시된 항목이 포함된 파일은 CLI든 UI든 SSH known hosts 추가 입력으로 쓸 수 없어요. 해시된 데이터를 꼭 써야 한다면 선언적 방법밖에 없는데, 그러면 CLI·UI 인증서 관리가 깨지니 일반적으로 권장하지 않아요.

CLI로 SSH known hosts를 등록할 수 있어요. --from <file>로 파일에서, 또는 --batch 지정 시 stdin으로 읽어요. ssh-keyscan server.example.com | argocd cert add-ssh --batch처럼 사용해요. existing known_hosts 파일을 가져올 땐 argocd cert add-ssh --batch --from /etc/ssh/ssh_known_hosts를 쓰면 돼요. 삭제는 argocd cert rm bitbucket.org --cert-type ssh로 하고, 키 서브타입이 여럿일 땐 --cert-sub-type으로 좁혀서 삭제할 수 있어요. SSH known hosts도 argocd-ssh-known-hosts-cm ConfigMap으로 선언형 관리가 가능해요.

Helm

보호된 Helm 저장소나 OCI 레지스트리에서도 차트를 가져올 수 있어요. HTTPS 기반 저장소의 _type_을 helm으로 지정해서 CLI나 UI로 접근을 설정해요.

CLI로는 argocd repo add 명령에 --type 플래그를 써요.

argocd repo add https://argoproj.github.io/argo-helm --type=helm <additional-flags>

UI에서는 Connect Repo 버튼에서 Connection Method를 VIA HTTPS로, Type을 helm으로 고르면 돼요.

보호된 OCI 레지스트리에서 Helm 차트를 쓰려면 위 형식에 더해 OCI임을 명시해야 해요. CLI로는 --enable-oci 플래그를 추가해요.

argocd repo add registry-1.docker.io/bitnamicharts --type=helm --enable-oci=true <additional-flags>

참고로 OCI 레지스트리를 참조할 때는 oci:// 같은 프로토콜을 생략해야 해요. UI에서는 helm 저장소 추가 시 Enable OCI 체크박스를 선택하면 돼요.

사용자 정의 HTTP User-Agent

일부 Helm 저장소 제공자(예: Wikimedia)는 로봇 액세스 정책으로 특정 User-Agent 헤더를 요구해요. Argo CD는 모든 Helm 저장소 요청에 기본 User-Agent 헤더(argocd-repo-server/<version> (<platform>))를 보내요. 조직 이름이나 연락처를 포함하도록 User-Agent를 바꾸려면 argocd-repo-server 배포에 ARGOCD_HELM_USER_AGENT 환경 변수를 설정해요. 이 변수는 모든 Helm 저장소 요청에 전역으로 적용돼요.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: argocd-repo-server
spec:
  template:
    spec:
      containers:
      - name: argocd-repo-server
        env:
        - name: ARGOCD_HELM_USER_AGENT
          value: "my-org/argocd ([email protected])"

Git 서브모듈

서브모듈은 지원되며 자동으로 감지돼요. 서브모듈 저장소가 인증을 요구하면 자격 증명이 부모 저장소의 것과 일치해야 해요. 서브모듈 지원을 끄려면 ARGOCD_GIT_MODULES_ENABLED=false로 설정하면 돼요.

프라이빗 저장소 연결하기