github.com/argoproj/argo-cd@v1.8.7/docs/user-guide/private-repositories.md (about) 1 # Private Repositories 2 3 !!!note 4 Some Git hosters - notably GitLab and possibly on-premise GitLab instances as well - require you to 5 specify the `.git` suffix in the repository URL, otherwise they will send a HTTP 301 redirect to the 6 repository URL suffixed with `.git`. ArgoCD will **not** follow these redirects, so you have to 7 adapt your repository URL to be suffixed with `.git`. 8 9 ## Credentials 10 11 If application manifests are located in private repository then repository credentials have to be configured. Argo CD supports both HTTP and SSH Git credentials. 12 13 ### HTTPS Username And Password Credential 14 15 Private repositories that require a username and password typically have a URL that start with `https://` rather than `git@` or `ssh://`. 16 17 Credentials can be configured using Argo CD CLI: 18 19 ```bash 20 argocd repo add https://github.com/argoproj/argocd-example-apps --username <username> --password <password> 21 ``` 22 23 or UI: 24 25 > v1.2 or later 26 27 1. Navigate to `Settings/Repositories` 28 29  30 31 1. Click `Connect Repo using HTTPS` button and enter credentials 32 33  34 35 *Note: username in screenshot is for illustration purposes only , we have no relationship to this GitHub account should it exist.* 36 37 1. Click `Connect` to test the connection and have the repository added 38 39 > earlier than v1.2 40 41 1. Navigate to `Settings/Repositories` 42 1. Click `Connect Repo` button and enter HTTP credentials 43 44  45 46 #### Access Token 47 48 Instead of using username and password you might use access token. Following instructions of your Git hosting service to generate the token: 49 50 * [Github](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) 51 * [Gitlab](https://docs.gitlab.com/ee/user/project/deploy_tokens/) 52 * [Bitbucket](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) 53 54 Then, connect the repository using any non-empty string as username and the access token value as a password. 55 56 !!!note 57 For some services, you might have to specify your account name as the username instead of any string. 58 59 ### TLS Client Certificates for HTTPS repositories 60 61 > v1.2 and later 62 63 If your repository server requires you to use TLS client certificates for authentication, you can configure ArgoCD repositories to make use of them. For this purpose, `--tls-client-cert-path` and `--tls-client-cert-key-path` switches to the `argocd repo add` command can be used to specify the files on your local system containing client certificate and the corresponding key, respectively: 64 65 ``` 66 argocd repo add https://repo.example.com/repo.git --tls-client-cert-path ~/mycert.crt --tls-client-cert-key-path ~/mycert.key 67 ``` 68 69 Of course, you can also use this in combination with the `--username` and `--password` switches, if your repository server should require this. The options `--tls-client-cert-path` and `--tls-client-cert-key-path` must always be specified together. 70 71 Your TLS client certificate and corresponding key can also be configured using the UI, see instructions for adding Git repos using HTTPS. 72 73 !!! note 74 Your client certificate and key data must be in PEM format, other formats (such as PKCS12) are not understood. Also make sure that your certificate's key is not password protected, otherwise it cannot be used by ArgoCD. 75 76 !!! note 77 When pasting TLS client certificate and key in the text areas in the web UI, make sure they contain no unintended line breaks or additional characters. 78 79 ### SSH Private Key Credential 80 81 Private repositories that require an SSH private key have a URL that typically start with `git@` or `ssh://` rather than `https://`. 82 83 > v1.2 or later 84 85 You can configure your Git repository using HTTPS either using the CLI or the UI. 86 87 Using the CLI: 88 89 ``` 90 argocd repo add git@github.com:argoproj/argocd-example-apps.git --ssh-private-key-path ~/.ssh/id_rsa 91 ``` 92 93 Using the UI: 94 95 1. Navigate to `Settings/Repositories` 96 97  98 99 1. Click `Connect Repo using SSH` button, enter the URL and paste the SSH private key 100 101  102 103 1. Click `Connect` to test the connection and have the repository added 104 105 !!!note 106 When pasting SSH private key in the UI, make sure there are no unintended line breaks or additional characters in the text area 107 108 !!!note 109 When your SSH repository is served from a non-standard port, you have to use `ssh://`-style URLs to specify your repository. The scp-style `git@yourgit.com:yourrepo` URLs do **not** support port specification, and will treat any port number as part of the repository's path. 110 111 > earlier than v1.2 112 113 The Argo CD UI don't support configuring SSH credentials. The SSH credentials can only be configured using the Argo CD CLI: 114 115 ``` 116 argocd repo add git@github.com:argoproj/argocd-example-apps.git --ssh-private-key-path ~/.ssh/id_rsa 117 ``` 118 119 ## Credential templates 120 121 > previous to v1.4 122 123 Credential templates are available only via declarative setup, see [Repository credentials](../../operator-manual/declarative-setup#repository-credentials) in Operator Manual. 124 125 > v1.4 and later 126 127 You can also set up credentials to serve as templates for connecting repositories, without having to repeat credential configuration. For example, if you setup credential templates for the URL prefix `https://github.com/argoproj`, these credentials will be used for all repositories with this URL as prefix (e.g. `https://github.com/argoproj/argocd-example-apps`) that do not have their own credentials configured. 128 129 To set up a credential template using the Web UI, simply fill in all relevant credential information in the __Connect repo using SSH__ or __Connect repo using HTTPS__ dialogues (as described above), but select __Save as credential template__ instead of __Connect__ to save the credential template. Be sure to only enter the prefix URL (i.e. `https://github.com/argoproj`) instead of the complete repository URL (i.e. `https://github.com/argoproj/argocd-example-apps`) in the field __Repository URL__ 130 131 To manage credential templates using the CLI, use the `repocreds` sub-command, for example `argocd repocreds add https://github.com/argoproj --username youruser --password yourpass` would setup a credential template for the URL prefix `https://github.com/argoproj` using the specified username/password combination. Similar to the `repo` sub-command, you can also list and remove repository credentials using the `argocd repocreds list` and `argocd repocreds rm` commands, respectively. 132 133 In order for ArgoCD to use a credential template for any given repository, the following conditions must be met: 134 135 * The repository must either not be configured at all, or if configured, must not contain any credential information 136 * The URL configured for a credential template (e.g. `https://github.com/argoproj`) must match as prefix for the repository URL (e.g. `https://github.com/argoproj/argocd-example-apps`). 137 138 !!! note 139 Repositories that require authentication can be added using CLI or Web UI without specifying credentials only after a matching repository credential has been set up 140 141 !!! note 142 Matching credential template URL prefixes is done on a _best match_ effort, so the longest (best) match will take precedence. The order of definition is not important, as opposed to pre v1.4 configuration. 143 144 The following is an example CLI session, depicting repository credential set-up: 145 146 ```bash 147 # Try to add a private repository without specifying credentials, will fail 148 $ argocd repo add https://docker-build/repos/argocd-example-apps 149 FATA[0000] rpc error: code = Unknown desc = authentication required 150 151 # Setup a credential template for all repos under https://docker-build/repos 152 $ argocd repocreds add https://docker-build/repos --username test --password test 153 repository credentials for 'https://docker-build/repos' added 154 155 # Repeat first step, add repo without specifying credentials 156 # URL for template matches, will succeed 157 $ argocd repo add https://docker-build/repos/argocd-example-apps 158 repository 'https://docker-build/repos/argocd-example-apps' added 159 160 # Add another repo under https://docker-build/repos, specifying invalid creds 161 # Will fail, because it will not use the template (has own creds) 162 $ argocd repo add https://docker-build/repos/example-apps-part-two --username test --password invalid 163 FATA[0000] rpc error: code = Unknown desc = authentication required 164 ``` 165 166 ## Self-signed & Untrusted TLS Certificates 167 168 > v1.2 or later 169 170 If you are connecting a repository on a HTTPS server using a self-signed certificate, or a certificate signed by a custom Certificate Authority (CA) which are not known to ArgoCD, the repository will not be added due to security reasons. This is indicated by an error message such as `x509: certificate signed by unknown authority`. 171 172 1. You can let ArgoCD connect the repository in an insecure way, without verifying the server's certificate at all. This can be accomplished by using the `--insecure-skip-server-verification` flag when adding the repository with the `argocd` CLI utility. However, this should be done only for non-production setups, as it imposes a serious security issue through possible man-in-the-middle attacks. 173 174 2. You can configure ArgoCD to use a custom certificate for the verification of the server's certificate using the `cert add-tls` command of the `argocd` CLI utility. This is the recommended method and suitable for production use. In order to do so, you will need the server's certificate, or the certificate of the CA used to sign the server's certificate, in PEM format. 175 176 !!! note 177 For invalid server certificates, such as those without matching server name, or those that are expired, adding a CA certificate will not help. In this case, your only option will be to use the `--insecure-skip-server-verification` flag to connect the repository. You are strongly urged to use a valid certificate on the repository server, or to urge the server's administrator to replace the faulty certificate with a valid one. 178 179 !!! note 180 TLS certificates are configured on a per-server, not on a per-repository basis. If you connect multiple repositories from the same server, you only have to configure the certificates once for this server. 181 182 !!! note 183 It can take up to a couple of minutes until the changes performed by the `argocd cert` command are propagated across your cluster, depending on your Kubernetes setup. 184 185 ### Managing TLS certificates using the CLI 186 187 You can list all configured TLS certificates by using the `argocd cert list` command using the `--cert-type https` modifier: 188 189 ```bash 190 $ argocd cert list --cert-type https 191 HOSTNAME TYPE SUBTYPE FINGERPRINT/SUBJECT 192 docker-build https rsa CN=ArgoCD Test CA 193 localhost https rsa CN=localhost 194 ``` 195 196 Example for adding a HTTPS repository to ArgoCD without verifying the server's certificate (**Caution:** This is **not** recommended for production use): 197 198 ```bash 199 argocd repo add --insecure-skip-server-verification https://git.example.com/test-repo 200 201 ``` 202 203 Example for adding a CA certificate contained in file `~/myca-cert.pem` to properly verify the repository server: 204 205 ```bash 206 argocd cert add-tls git.example.com --from ~/myca-cert.pem 207 argocd repo add https://git.example.com/test-repo 208 ``` 209 210 You can also add more than one PEM for a server by concatenating them into the input stream. This might be useful if the repository server is about to replace the server certificate, possibly with one signed by a different CA. This way, you can have the old (current) as well as the new (future) certificate co-existing. If you already have the old certificate configured, use the `--upsert` flag and add the old and the new one in a single run: 211 212 ```bash 213 cat cert1.pem cert2.pem | argocd cert add-tls git.example.com --upsert 214 ``` 215 216 !!! note 217 To replace an existing certificate for a server, use the `--upsert` flag to the `cert add-tls` CLI command. 218 219 Finally, TLS certificates can be removed using the `argocd cert rm` command with the `--cert-type https` modifier: 220 221 ```bash 222 argocd cert rm --cert-type https localhost 223 ``` 224 225 ### Managing TLS certificates using the ArgoCD web UI 226 227 It is possible to add and remove TLS certificates using the ArgoCD web UI: 228 229 1. In the navigation pane to the left, click on "Settings" and choose "Certificates" from the settings menu 230 231 1. The following page lists all currently configured certificates and provides you with the option to add either a new TLS certificate or SSH known entries: 232 233  234 235 1. Click on "Add TLS certificate", fill in relevant data and click on "Create". Take care to specify only the FQDN of your repository server (not the URL) and that you C&P the complete PEM of your TLS certificate into the text area field, including the `----BEGIN CERTIFICATE----` and `----END CERTIFICATE----` lines: 236 237  238 239 1. To remove a certificate, click on the small three-dotted button next to the certificate entry, select "Remove" from the pop-up menu and confirm the removal in the following dialogue. 240 241  242 243 ### Managing TLS certificates using declarative configuration 244 245 You can also manage TLS certificates in a declarative, self-managed ArgoCD setup. All TLS certificates are stored in the ConfigMap object `argocd-tls-cert-cm`. 246 Please refer to the [Operator Manual](../../operator-manual/declarative-setup/#repositories-using-self-signed-tls-certificates-or-are-signed-by-custom-ca) for more information. 247 248 > Before v1.2 249 250 We do not currently have first-class support for this. See [#1513](https://github.com/argoproj/argo-cd/issues/1513). 251 252 As a work-around, you can customize your Argo CD image. See [#1344](https://github.com/argoproj/argo-cd/issues/1344#issuecomment-479811810) 253 254 ## Unknown SSH Hosts 255 256 If you are using a privately hosted Git service over SSH, then you have the following options: 257 258 > v1.2 or later 259 260 1. You can let ArgoCD connect the repository in an insecure way, without verifying the server's SSH host key at all. This can be accomplished by using the `--insecure-skip-server-verification` flag when adding the repository with the `argocd` CLI utility. However, this should be done only for non-production setups, as it imposes a serious security issue through possible man-in-the-middle attacks. 261 262 2. You can make the server's SSH public key known to ArgoCD by using the `cert add-ssh` command of the `argocd` CLI utility. This is the recommended method and suitable for production use. In order to do so, you will need the server's SSH public host key, in the `known_hosts` format understood by `ssh`. You can get the server's public SSH host key e.g. by using the `ssh-keyscan` utility. 263 264 !!! note 265 It can take up to a couple of minutes until the changes performed by the `argocd cert` command are propagated across your cluster, depending on your Kubernetes setup. 266 267 !!! note 268 When importing SSH known hosts key from a `known_hosts` file, the hostnames or IP addresses in the input data must **not** be hashed. If your `known_hosts` file contains hashed entries, it cannot be used as input source for adding SSH known hosts - neither in the CLI nor in the UI. If you absolutely wish to use hashed known hosts data, the only option will be using declarative setup (see below). Be aware that this will break CLI and UI certificate management, so it is generally not recommended. 269 270 ### Managing SSH Known Hosts using the CLI 271 272 You can list all configured SSH known host entries using the `argocd cert list` command with the `--cert-type ssh` modifier: 273 274 ```bash 275 $ argocd cert list --cert-type ssh 276 HOSTNAME TYPE SUBTYPE FINGERPRINT/SUBJECT 277 bitbucket.org ssh ssh-rsa SHA256:zzXQOXSRBEiUtuE8AikJYKwbHaxvSc0ojez9YXaGp1A 278 github.com ssh ssh-rsa SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8 279 gitlab.com ssh ecdsa-sha2-nistp256 SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw 280 gitlab.com ssh ssh-ed25519 SHA256:eUXGGm1YGsMAS7vkcx6JOJdOGHPem5gQp4taiCfCLB8 281 gitlab.com ssh ssh-rsa SHA256:ROQFvPThGrW4RuWLoL9tq9I9zJ42fK4XywyRtbOz/EQ 282 ssh.dev.azure.com ssh ssh-rsa SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og 283 vs-ssh.visualstudio.com ssh ssh-rsa SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og 284 ``` 285 286 For adding SSH known host entries, the `argocd cert add-ssh` command can be used. You can either add from a file (using the `--from <file>` modifier), or by reading `stdin` when the `--batch` modifier was specified. In both cases, input must be in `known_hosts` format as understood by the OpenSSH client. 287 288 Example for adding all available SSH public host keys for a server to ArgoCD, as collected by `ssh-keyscan`: 289 290 ```bash 291 ssh-keyscan server.example.com | argocd cert add-ssh --batch 292 293 ``` 294 295 Example for importing an existing `known_hosts` file to ArgoCD: 296 297 ```bash 298 argocd cert add-ssh --batch --from /etc/ssh/ssh_known_hosts 299 ``` 300 301 Finally, SSH known host entries can be removed using the `argocd cert rm` command with the `--cert-type ssh` modifier: 302 303 ```bash 304 argocd cert rm bitbucket.org --cert-type ssh 305 ``` 306 307 If you have multiple SSH known host entries for a given host with different key sub-types (e.g. as for gitlab.com in the example above, there are keys of sub-types `ssh-rsa`, `ssh-ed25519` and `ecdsa-sha2-nistp256`) and you want to only remove one of them, you can further narrow down the selection using the `--cert-sub-type` modifier: 308 309 ```bash 310 argocd cert rm gitlab.com --cert-type ssh --cert-sub-type ssh-ed25519 311 ``` 312 313 ### Managing SSH known hosts data using the ArgoCD web UI 314 315 It is possible to add and remove SSH known hosts entries using the ArgoCD web UI: 316 317 1. In the navigation pane to the left, click on "Settings" and choose "Certificates" from the settings menu 318 319 1. The following page lists all currently configured certificates and provides you with the option to add either a new TLS certificate or SSH known entries: 320 321  322 323 1. Click on "Add SSH known hosts" and paste your SSH known hosts data in the following mask. **Important**: Make sure there are no line breaks in the entries (key data) when you paste the data. Afterwards, click on "Create". 324 325  326 327 1. To remove a certificate, click on the small three-dotted button next to the certificate entry, select "Remove" from the pop-up menu and confirm the removal in the following dialogue. 328 329  330 331 ### Managing SSH known hosts data using declarative setup 332 333 You can also manage SSH known hosts entries in a declarative, self-managed ArgoCD setup. All SSH public host keys are stored in the ConfigMap object `argocd-ssh-known-hosts-cm`. For more details, please refer to the [Operator Manual](../../operator-manual/declarative-setup/#ssh-known-host-public-keys) 334 335 > Before v1.2 336 337 338 (1) You can customize the Argo CD Docker image by adding the host's SSH public key to `/etc/ssh/ssh_known_hosts`. Additional entries to this file can be generated using the `ssh-keyscan` utility (e.g. `ssh-keyscan your-private-git-server.com`. For more information see [example](https://github.com/argoproj/argo-cd/tree/master/examples/known-hosts) which demonstrates how `/etc/ssh/ssh_known_hosts` can be customized. 339 340 !!! note 341 The `/etc/ssh/ssh_known_hosts` should include Git host on each Argo CD deployment as well as on a computer where `argocd repo add` is executed. After resolving issue 342 [#1514](https://github.com/argoproj/argo-cd/issues/1514) only `argocd-repo-server` deployment has to be customized. 343 344 (1) Add repository using Argo CD CLI and `--insecure-ignore-host-key` flag: 345 346 ```bash 347 argocd repo add git@github.com:argoproj/argocd-example-apps.git --ssh-private-key-path ~/.ssh/id_rsa --insecure-ignore-host-key 348 ``` 349 350 !!! warning "Don't use in production" 351 The `--insecure-ignore-host-key` should not be used in production as this is subject to man-in-the-middle attacks. 352 353 !!! warning "This does not work for Kustomize remote bases or custom plugins" 354 For Kustomize support, see [#827](https://github.com/argoproj/argo-cd/issues/827). 355 356 ## Git Submodules 357 358 > v1.4 or later 359 360 Submodules are supported and will be picked up automatically. If the submodule repository requires authentication then the credentials will need to match the credentials of the parent repository. Set ARGOCD_GIT_MODULES_ENABLED=false to disable submodule support 361 362 ## Declarative Configuration 363 364 See [declarative setup](../../operator-manual/declarative-setup#Repositories) 365