Checking out Git Repositories

Basics

Oftentimes in CI / CD pipelines, you will want to checkout code from a private repository in order to execute your CI / CD logic against it.

We provide a utility command in the devenv called pf-wf-git-checkout that efficiently checks out a given repository to a given git ref using provided credentials.

For example, you might call the command as follows:

pf-wf-git-checkout \
    --username fullykubed \
    --password "$GITHUB_TOKEN" \
    --repo github.com/fullykubed/test \
    --checkout main

In addition to checking out the repo, this command does the following:

Persists the authentication information for the repository so that future git commands on the repository do not need to be explicitly authenticated.
Enables Git LFS tooling and pulls any associated files if the repo uses LFS.
Changes the current working directory to the local repository directory.

You can use the Panfactum devenv and scripts like this in your workflows by following this guide section.

We recommend running this script as one of the first parts ContainerSet template. You can find a full example of this in action here.

Note that this performs a shallow clone, so if you need to interact with commits other than what is supplied by --checkout, you will need to explicitly git fetch them first.

Credentials

The authentication provided to this command ultimately resolves to this format:

git clone https://<username>:<password>@<repo>.git

While this is supported by all major git hosting providers, the exact values may differ for username and password. Below we outline some common scenarios:

Using a GitHub classic Personal Access Token (PAT):
- username: the account's username
- password: the PAT
Using a GitHub fine-grained Personal Access Token (PAT):
- username: set to oauth2
- password: the PAT
Using a GitLab Personal Access Token (PAT):
- username: the account's username
- password: the PAT
Using a Bitbucket Repository Access Token (RAT):
- username: set to x-token-auth
- password: the RAT