/checkout-orb

Orb helping to do advanced checkouts.

Primary LanguageShellMIT LicenseMIT

rynkowsg/checkout orb

CircleCI Build Status CircleCI Orb Version License CircleCI Community

CircleCI orb for advanced checkouts.

Motivation

The standard checkout command is good for basic stuff, but when you need to do more, it can get tricky. This orb makes those tricky things easier.

What it does:

  • Supports shallow clones, so you can

    • grab just the latest commit if that's all you need, or
    • get the last few commits, depending on what you need,
    • supports smart deepen - if depth is too shallow, try 10 times to deepen.

  • Supports cloning to existed already repository

    • e.g. if you persist or cache repository

  • Works with LFS (Large File Storage), so you can:

    • get LFS files in your repo, or
    • choose not to get LFS files if you don't need them.

  • Helps with submodules in a couple of ways:

    • you can clone repos that have submodules,
    • you can also clone repos without bringing along the submodules.

  • Lets you use your own SSH keys.

  • Supports running job locally on your machine.

  • Supports usage of GitHub token for fetching public repositories.

Quickstart

The simplest possible case includes replacement of checkout to checkout/checkout.

version: '2.1'

orbs:
  checkout: rynkowsg/checkout@0.3.0

jobs:
  test:
    docker: [{image: "cimg/base:stable"}]
    steps:
      - checkout/checkout

workflows:
  main-workflow:
    jobs:
      - test

Usage

Shallow clone

jobs:
  test:
    steps:
      - checkout/checkout:
          depth: 1

Setting depth: 1 will clone only the top commit whether checking out the branch or a tag.

Clone with LFS support

jobs:
  test:
    steps:
      - checkout/checkout:
          with_lfs: true

Clone with submodules

jobs:
  test:
    steps:
      - checkout/checkout:
          with_submodules: true

Clone additional repository

jobs:
  test:
    # ...
    steps:
      - checkout/checkout
      - checkout/checkout:
          repo_url: "https://github.com/rynkowsg/test-clone-repo-l0.git"
          repo_branch: "master"
          repo_sha1: "f731330"
          dest_dir: /tmp/test-clone

In this case, we first clone the current repository, and then additional one to given destination.

WARNING: If the dest_dir is not provided, the command will fail because both will try to clone the repo to the default location ~/project.

Authenticate with GitHub token

If GitHub token is available all HTTPS clones uses it. It can be provided by:

  • command param github-token or
  • in environment variable GITHUB_TOKEN.

Authenticate with custom SSH identity

The SSH identity provided by default in CircleCI job allows only to fetch the current repository. Some scenarios when it is problematic includes:

  • when you fetch private repo other than current,
  • you employ submodules in your repository from which some are private.

In such a case you need to provide additional SSH identity with access for given repository. Either via CircleCI dashboard or with environment variables. It can be done by providing one of two environment variables:

  • CHECKOUT_KEY - private key in plain text
  • SSH_PRIVATE_KEY_B64 - private key in base64.

For more guidelines and examples, see the orb registry listing.

Contributing

I welcome issues to and pull requests against this repository!

More

Similar projects

rynkowsg/ orb family

Name Description
rynkowsg/asdf Orb providing support for ASDF
rynkowsg/checkout Advanced checkout with support of LFS, submodules, custom SSH identities, shallow clones and more
rynkowsg/rynkowsg Orb with no particular theme, used primarily for prototyping

License

Copyright © 2024 Greg Rynkowski

Released under the MIT license.