Introduction
Understanding organizationsUnderstanding componentsManage organizationsManage componentsManage component Jira integrations
Set up your first organizationUnderstanding users and teamsUnderstanding role-based access controlManage usersManage teamsConfigure role-based access controlRBAC permissions reference
Understanding authentication in CloudBees UnifySet up multifactor authenticationConfigure SAML single sign-onConfigure OIDC authenticationConfigure network security policiesNetwork security reference
Understanding platform configurationUnderstanding environmentsManage properties and secretsManage environmentsTrack environment inventoryConfigure containersSet up preconfigured actionsConfigure notifications
Accessibility policy referenceShared responsibility model referenceSubscription and services agreementSupport policiesSupported browsers and external tools
Introduction
Understanding feature managementUnderstanding Configuration as CodeGet started with feature managementCreate and manage feature flagsConfigure feature flag targetingOrganize feature flagsImplement feature flag governanceConfiguration as Code reference
Understanding flag impressions and activity statusUnderstanding flag healthUnderstanding code referencesReview and clean up feature flagsSet up code references
Understanding Jira integration for feature flagsSet up the Jira integrationLink Jira tickets to feature flags
Understanding multiple SDK keysBuild your first mobile app with feature flagsBuild your first feature-flagged web applicationBuild your first feature-flagged backend serviceInstall client-side SDKsInstall server-side SDKsConfigure multiple SDK keysMobile SDK referenceWeb SDK referenceBackend SDK referenceClient SDK referenceFlag implementation reference
Introduction
Understanding CI workflowsCreate a build workflowCreate and manage workflowsCreate reusable workflowsTest and validate containers in workflowsCheck out source codeTrigger workflows remotelyWorkflow syntax referenceJobs syntax referenceSteps syntax referenceServices syntax reference
Monitor workflow runsView test results in runsView evidence in runsView deployments in runsManage workflow artifactsPublish test resultsPublish evidence itemsGenerate a software bill of materialsManage ServiceNow change requests
Configure workflow credentialsConfigure AWS credentialsConfigure container registry credentialsConfigure Git credentialsIntegrate external secret providers
Understanding GitHub Actions integrationSet up GitHub Actions integrationDisplay GitHub Actions workflows and runsRegister GHA build artifactsPublish GHA deployed artifactsPublish GHA test resultsPublish GHA evidence itemsTrigger CloudBees workflows from GitHub ActionsScan with GitHub Actions
Understanding CloudBees CI and Jenkins® integrationConnect CI and Jenkins controllersMonitor CI and Jenkins buildsRegister CI build artifactsRegister CI deployed artifactsPublish CI test resultsConfigure CI security scanningCI and Jenkins integration reference
Build and publish container imagesUnderstanding external CI/CD integrationsRun external CI/CD jobsExternal CI/CD action reference
Introduction
Understanding release orchestrationManage applicationsCreate deployer workflowsCreate staged workflowsCreate and manage releasesOrchestrate multi-workflow releasesRelease management reference
Understanding artifact managementRegister and track artifactsStore and retrieve artifactsPromote artifactsGenerate a software bill of materialsArtifact management reference
Deploy with HelmDeploy to KubernetesContainer deployment reference
Deploy to AWSAWS deployment reference
Deploy with enterprise platformsExecute remote deployment commandsEnterprise deployment reference
Verify deployments with New RelicDeployment verification reference

Check out source code

5 minute read

Check out a Git repository into $CLOUDBEES_WORKSPACE so your workflow steps can access source code. Authentication is persisted in the local Git config by default, enabling authenticated Git commands in any container image that has git executables.

Authenticate the checkout

By default, the checkout action uses the CloudBees workflow run token (cloudbees.api.token) to fetch an app access token. If you provide an ssh-key input, the SSH key is used instead.

  • 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 Workflow syntax reference.

CloudBees recommends using platform authentication instead of SSH keys. Do not use SSH keys when the authentication built into CloudBees Unify for the workflow repository is available, or when the configure-git-global-credentials action can be used.

Check out a repository

To check out a repository:

  1. Add the checkout step to your workflow YAML, setting uses to https://github.com/cloudbees-io/checkout@v2.

  2. Set the repository input to the clone URL of your repository.

    The default value is ${{ cloudbees.scm.repository }}, which checks out the triggering workflow’s repository.

The following example checks 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 checks 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
▼

Configure checkout options

The checkout action supports several inputs to control what is fetched and how authentication is handled.

Specify a branch, tag, or commit

Use the ref input to check out a specific branch, tag, or SHA.

The following example checks out the test branch of a Bitbucket repository from 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
▼

Fetch full history

By default, the action fetches only the most recent commit (fetch-depth: 1). Set fetch-depth: 0 to fetch the full history for all branches and tags.

The following example fetches the full history of the default branch using an SSH key, without persisting credentials:

      - 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
▼

Check out submodules

Set submodules: true to check out submodules, or submodules: recursive to check out submodules recursively.

The following example checks out the last commit of the default branch with submodules checked out recursively into a specified path:

      - 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
▼
When the ssh-key input is not provided, SSH URLs beginning with git@github.com: are converted to HTTPS.

Download Git LFS files

Set lfs: true to download Git Large File Storage (LFS) files during checkout. The default is false.

Access checkout outputs

To access the checkout outputs in a later workflow step:

  1. Add an id field to your checkout step, for example id: checkout.

  2. Reference the outputs using the expression ${{ steps.checkout.outputs.<output-name> }}.

The following example displays all three checkout outputs:

- 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 }}
▼

Inputs

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

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 the 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.

lfs

Boolean

No

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

path

String

No

The relative repository path under $CLOUDBEES_WORKSPACE.

persist-credentials

Boolean

No

Default is true. When true, the SSH key is configured within the local Git config, enabling subsequently run scripts to execute using authenticated Git commands.

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 which case the event reference or SHA is used.

repository

String

No

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

set-safe-directory

Boolean

No

Default is true. When true, adds the 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, enabling scripts to run authenticated Git commands.

CloudBees recommends using CloudBees Unify authentication instead of SSH keys. Do not use SSH keys if authentication built into CloudBees Unify for the workflow repository is available, or if the configure-git-global-credentials action can be used.

When adding the SSH private key as a secret in CloudBees Unify, ensure the string ends with a new line.

The cloudbees-io/checkout@v1 version of the action continues to work with GitHub, GitHub Enterprise, Bitbucket Cloud, and Bitbucket Data Center. For other SCM providers such as Gerrit or GitLab, use cloudbees-io/checkout@v2.

ssh-known-hosts

String

No

A list of known SSH hosts to add to the global host database. Use the ssh-keyscan utility 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 ssh-known-hosts input 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.

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.

Migrate from v1 to v2

Version 2 of the checkout action is SCM-provider-agnostic. The repository input now takes the full clone URL (for example, https://github.com/cloudbees-io/checkout), with a default value of ${{ cloudbees.scm.repository }}.

The following inputs and outputs were removed in v2:

Table 3. Removed inputs and outputs
Removed input Removed output

token

commit-url

token-auth-type

provider

github-server-url

bitbucket-server-url

gitlab-server-url

The token and token-auth-type inputs are not supported in v2. For workflows that previously used these inputs, the repository must now either be integrated with CloudBees Unify or accessed using SSH keys.

The provider, github-server-url, bitbucket-server-url, and gitlab-server-url inputs are no longer required. These values are derived automatically from the repository field.

Related pages

Test and validate containers in workflows
Trigger workflows remotely