CloudBees action: Check out a Git repository

4 minute read

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

Check out a repository from any of the following source code management (SCM) providers:

  • GitHub

  • Bitbucket

  • Bitbucket Data Center

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

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 from the SCM provider if neither a personal access token nor an SSH key are specified.

  • 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

Table 1. Input details
Input name Data type Required? Description

repository

String

Yes

Repository name with owner, for example, actions/checkout.

provider

String

Required only if you are checking out a repository from an SCM provider different from the provider that hosts your CloudBees platform workflow.

Specify bitbucket, bitbucket_datacenter, or github, as appropriate.

bitbucket-server-url

String

Required only if you are checking out a repository from Bitbucket or Bitbucket Data Center, and that is not the SCM provider hosting your platform workflow. Unless specified, the base URL uses environment defaults to fetch from the same instance the workflow is running from.

The base URL, for example, https://bitbucket.org or https://my-bbdc-server.example.com.

github-server-url

String

Required only if you are checking out a repository from GitHub, and that is not the SCM provider hosting your platform workflow. Unless specified, the base URL uses environment defaults to fetch from the same instance the workflow is running from.

The base URL, for example, https://github.com.

clean

Boolean

No

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

fetch-depth

Number

No

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

lfs

Boolean

No

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

path

String

No

The relative path to place the repository under $CLOUDBEES_WORKSPACE.

persist-credentials

Boolean

No

Default is true. When true, the token or SSH key is configured with the local Git config.

ref

String

No

The branch, tag or SHA to check out. The action uses your default branch, unless you check out a repository that is triggered from a workflow, in which case it defaults to the reference or SHA for that event.

set-safe-directory

Boolean

No

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

No

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

ssh-known-hosts

String

No

Known hosts in addition to the user and global host key database. Use the utility ssh-keyscan to get public SSH keys for a host. For example, use ssh-keyscan my-ssh-server.example.com to get the keys for your self-hosted SSH server at my-ssh-server.example.com. The public keys for GitHub, Bitbucket, and GitLab are already added by default.

ssh-strict

Boolean

No

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

No

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.

token

String

No

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

token-auth-type

String

No

The authentication type of the token being used. Supported values are basic and bearer. Default is basic.

Usage examples

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

- name: Check out my GitHub repo uses: https://github.com/cloudbees-io/checkout@v1 (1) with: repository: my-name/my-repo-name
1 The action’s full URL is not required here, because the action and workflow both reside with the same SCM provider. However, CloudBees recommends that you clearly identify the repository with the full action URL.

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@v1 (1) with: repository: my-name/my-repo-name
1 You must use the action’s full URL for checking out Bitbucket or Bitbucket Data Center repositories in this case, because the action repository is hosted on GitHub.

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@v1 with: provider: bitbucket repository: my-name/my-repo-name bitbucket-server-url: https://bitbucket.org ref: test token: ${{ secrets.MY_BITBUCKET_TOKEN }}

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@v1 with: repository: my-name/my-repo-name github-server-url: https://github.com 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, using the CloudBees workflow run token. Submodules are recursively checked out.

- name: Check out GitHub repo uses: https://github.com/cloudbees-io/checkout@v1 with: repository: my_name/my_repo token: ${{ cloudbees.scm.token }} path: my_path fetch-depth: 1 submodules: recursive