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 your scripts can run authenticated Git commands in any container image that has Git executables.

The CloudBees API token is used to fetch an app access token if neither the PAT nor a SSH key are provided.

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 [email protected]: 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 example

In the YAML file, all values are required, unless otherwise noted. Default values are included in the example YAML file below. Refer to the notes for options and details.

Note	CloudBees recommends: Use a service account that limits user access to only necessary permissions. When generating a new PAT, select the narrowest possible scope.

In your YAML file, add:

      - name: Check out repo
        uses: cloudbees-io/checkout@v1
        id: checkout
        with:
          provider: ${{ cloudbees.scm.provider }}
          repository: ${{ cloudbees.repository }}
          ref: ''
          token: ${{ cloudbees.scm.token }}
          ssh-key: ''
          ssh-known-hosts: ''
          ssh-strict: true
          persist-credentials: true
          path: ''
          clean: true
          fetch-depth: 1
          lfs: false
          submodules: false
          set-safe-directory: true
          github-server-url: ''
          bitbucket-server-url: ''
          gitlab-server-url: ''
      - 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 }}

License

This code is made available under the MIT license.

References

• Learn more about using actions in CloudBees workflows.

• Learn about the CloudBees platform.