CloudBees action: Check out a Git repository

Use this action to check out a Git repository under $CLOUDBEES_WORKSPACE, to allow your workflow to access the repository.

Your authentication for the checked-out repository is persisted in the local Git config file by default, so scripts can run authenticated Git commands in any container image that has git executables.

All CloudBees action repositories are listed at CloudBees, Inc. on GitHub.

Workflow run tokens

The CloudBees workflow run token (cloudbees.api.token) is used to fetch an app access token if no SSH key is provided.

Use a service account that limits user access to only necessary permissions.
When generating a new personal access token, select the narrowest possible scope.
Your CloudBees workflow run token can also be exchanged for OIDC tokens for use with Amazon Web Services, Google Cloud Platform, and other external tools. To learn more, refer to cloudbees and other context objects.

Inputs

Input name Data type Required? Description

clean

Boolean

Default is true. When true, executes git clean -ffdx && git reset --hard HEAD before fetching.

cloudbees-api-token

String

The CloudBees API Token to use when fetching SCM token when a token or ssh-key are not used. Default value is ${{ cloudbees.api.token }}.

fetch-depth

Number

Number of commits to fetch. Default is 1. 0 indicates a full history for all branches and tags.

lfs

Boolean

Default is false. When true, downloads Git-LFS files.

path

String

The relative repository path under the $CLOUDBEES_WORKSPACE.

persist-credentials

Boolean

The default value is true. When true, the SSH key is configured within the local Git config. This enables subsequently run scripts to execute using authenticated Git commands.

ref

String

The branch, tag or SHA to check out. The action uses the default branch, except when checking out the triggering workflow repository. In that instance, the event reference or SHA is used.

repository

String

Repository clone URL. For example, https://github.com/cloudbees-io/checkout. Default value is ${{ cloudbees.scm.repository }}.

set-safe-directory

Boolean

Default is true. When true, adds a repository path as safe.directory for the Git global config, by running git config --global --add safe.directory <path>.

ssh-key

String

SSH key used to fetch the repository. The SSH key is configured with the local Git config, which enables scripts to run authenticated Git commands.

We recommend using the platform authentication instead of SSH keys. Do not use SSH keys if using the authentication built into the platform for the workflow repository or authentication using the configure-git-global-credentials action is possible.

When adding the SSH private key as a Secret on CloudBees platform, ensure the string being added to the Secret value ends with a new line.

The cloudbees-io/checkout@v1 version of the action will continue to work with GitHub, GitHub Enterprise, Bitbucket cloud, and Bitbucket Datacenter. For other SCM providers (for instance Gerrit or GitLab) use the cloudbees-io/checkout@v2 version of this action.

ssh-known-hosts

String

A list of known SSH hosts that should be added to the global host database. Use the utility ssh-keyscan to get public SSH keys for a host.

The public keys for GitHub and Bitbucket are implicitly added by default.

ssh-strict

Boolean

Default is true. When true, performs strict host key checking, by adding the options StrictHostKeyChecking=yes and CheckHostIP=no to the SSH command line. Use the input ssh-known-hosts to configure additional hosts.

submodules

Boolean

Default is false. When true, checks out submodules. Use the value recursive, to recursively check out submodules. When the ssh-key input is not provided, SSH URLs beginning with git@github.com: are converted to HTTPS.

Outputs

Table 2. Output details
Output name	Data type	Description
`commit`	String	The commit SHA for the source repository.
`ref`	String	The ref or branch for the checked-out repository. Returns empty when in a detached-head state or if the commit is from a local merge.
`repository-url`	String	The URL of the cloned repository.

Usage examples

The following example uses this action to check out a GitHub repository:

      - name: Check out my GitHub repo
        uses: https://github.com/cloudbees-io/checkout@v2 (1)
        with:
          repository: https://github.com/my-name/my-repo-name▼

1	The full URL for the action is not required. CloudBees recommends using the full action URL to ensure clear identification. However, the short form can be used when the action resides in a Github SaaS repository.

The following example uses this action to check out a Bitbucket (cloud) or Bitbucket Data Center repository:

      - name: Check out my Bitbucket repo
        uses: https://github.com/cloudbees-io/checkout@v2
        with:
          repository: https://bitbucket.org/my-name/my-repo-name▼

The following example uses this action to check out the test branch of a Bitbucket repository for a workflow hosted in a GitHub repository:

      - name: Check out Bitbucket repo for GitHub workflow
        uses: https://github.com/cloudbees-io/checkout@v2
        with:
          repository: https://bitbucket.org/my-name/my-repo-name
          ref: test▼

The following example uses this action to check out the full history of the default branch of a GitHub repository, using an SSH key. The authentication does not persist.

      - name: Check out GitHub repo
        uses: https://github.com/cloudbees-io/checkout@v2
        with:
          repository: https://github.com/my-name/my-repo-name
          ssh-key: {{ secrets.MY_SSH_KEY }}
          persist-credentials: false
          fetch-depth: 0▼

The following example uses this action to check out the last commit of the default branch of a GitHub repository. Submodules are recursively checked out.

      - name: Check out GitHub repo
        uses: https://github.com/cloudbees-io/checkout@v2
        with:
          repository: https://github.com/my_name/my_repo
          path: my_path
          fetch-depth: 1
          submodules: recursive▼

The following example uses the outputs context variable to access the action’s output values.

- name: Display outputs
  uses: docker://golang:1.20.3-alpine3.17
  shell: sh
  run: |
          echo Repository URL = ${{ steps.checkout.outputs.repository-url }}
          echo Commit ID = ${{ steps.checkout.outputs.commit }}
          echo Ref = ${{ steps.checkout.outputs.ref }}▼