Remote authentication

Registries and vcpkg_from_git() directly use the Git command line tools to fetch remote resources. Some of these resources may be protected from anonymous access and need authentication or credentials.

The strategies below all seek to achieve the same fundamental goal: git clone https://.... should succeed without interaction. This enables vcpkg to be separated from the specifics of your authentication scheme, ensuring forward compatibility with any additional security improvements in the future.

Pre-seed git credentials

You can pre-seed git credentials via git credential approve:

Powershell:

"url=https://github.com`npath=Microsoft/vcpkg`nusername=unused`npassword=$MY_PAT`n" | git credential approve

Bash:

echo "url=https://github.com"$'\n'"path=Microsoft/vcpkg"$'\n'"username=unused"$'\n'"password=$MY_PAT"$'\n' | git credential approve

Bearer auth

For systems which need bearer auth, you can use git config:

Note

You must make these config changes with --global

git config --global --unset-all http.<uri>.extraheader
git config --global http.<uri>.extraheader "AUTHORIZATION: bearer <System_AccessToken>"

The <uri> can be filled in with a variety of options, for example https://dev.azure.com/MYORG/. For more details, see the git config documentation.

(Original source in: Best way to authenticate against a git repository in a build process).

Azure DevOps users: You may need to enable access via Job authorization scope and reference the repo in your yaml pipeline:

resources: 
  repositories:
    - repository: <FRIENDLYNAME>
      type: git
      name: <ORG>/<REPO>
      tag: tags/<TAG>

...

jobs:
 - job: Build
   uses:
     repositories: [<FRIENDLYNAME>]

Pass credentials in an environment variable (not recommended)

Using VCPKG_KEEP_ENV_VARS or VCPKG_ENV_PASSTHROUGH_UNTRACKED, you can pass credentials in via the environment.

export VCPKG_KEEP_ENV_VARS=MY_TOKEN_VAR
export MY_TOKEN_VAR=abc123

This can then be used in your private ports with the pvcpkg_from_git() or vcpkg_from_github() helpers.

# vcpkg-from-git-example/portfile.cmake
set(MY_TOKEN_VAR "")
if(DEFINED ENV{MY_TOKEN_VAR})
    set(MY_TOKEN_VAR "$ENV{MY_TOKEN_VAR}@")
endif()
vcpkg_from_git(
    URLS "https://${MY_TOKEN_VAR}host.com/normal/url/path"
    ...
)

# vcpkg-from-github-example/portfile.cmake
vcpkg_from_github(
    AUTHORIZATION_TOKEN "$ENV{MY_TOKEN_VAR}"
)

For private ports, we recommend using vcpkg_from_git() instead of vcpkg_from_github() and the pre-seeding method above.

Pass Jenkins gitUsernamePassword credentials

The simplest and most secure option to Git authentication to GitHub from Jenkins is using GitHub App and the following:

withCredentials([gitUsernamePassword(credentialsId: 'jenkins-github-app')]) {
  withEnv(['VCPKG_KEEP_ENV_VARS=GIT_ASKPASS']) {
    bat 'cmake'
  }
}

This sets the GIT_ASKPASS with a path to helper script which responds with git credentials query and instructs vcpkg to keep this environment variable. The password is a GitHub App token with 1 hour lifetime.