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.

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
`bitbucket-server-url`	String	No	The base URL for the Bitbucket instance to clone. The environment defaults, such as `BITBUCKET_SERVER_URL` are used to fetch the same instance running the workflow. Example URLs: `https://bitbucket.org` or `https://my-bbdc-server.example.com`.
`clean`	Boolean	No	Default is `true`. When `true`, executes `git clean -ffdx && git reset --hard HEAD` before fetching.
`cloudbees-api-token`	String	No	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	No	Number of commits to fetch. Default is `1`. `0` indicates a full history for all branches and tags.
`github-server-url`	String	No	The base URL for the GitHub instance to clone. The environment defaults, such as `GITHUB_SERVER_URL` are used to fetch the same instance running the workflow. Example URLs: `https://github.com` or `https://my-ghes-server.example.com`.
`lfs`	Boolean	No	Default is `false`. When `true`, downloads Git-LFS files.
`path`	String	No	The relative repository path under the `$CLOUDBEES_WORKSPACE`.
`persist-credentials`	Boolean	No	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.
`provider`	String	No	The SCM provider hosting the repository. For example GitHub, BitBucket, or custom. The default is `${{ cloudbees.scm.provider }}`.
`ref`	String	No	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	No	The repository name with owner. For example, `actions/checkout`. Default value is `${{ cloudbees.scm.repository }}`.
`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 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.
`ssh-known-hosts`	String	No	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	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`.

Outputs

Table 2. Output details
Output name	Data type	Description
`commit`	String	The commit SHA for the source repository.
`commit-url`	String	The commit URL from the source repository. Returns Unavailable if the commit is from a local merge.
`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 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▼

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▼

The following example uses outputs to display action input 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 Commit URL = ${{ steps.checkout.outputs.commit-url }}
          echo Ref = ${{ steps.checkout.outputs.ref }}▼