step.yml

title: Git Clone Repository
summary: Checks out the repository, updates submodules and exports git metadata as Step outputs.
description: |
  The checkout process depends on the Step settings and the build trigger parameters (coming from your git server).

  Depending on the conditions, the step can checkout:
  - the merged state of a Pull Request
  - the head of a Pull Request
  - a git tag
  - a specific commit on a branch
  - the head of a branch

  The Step also supports more advanced features, such as updating submodules and sparse checkouts.

  ### Configuring the Step

  The step should work with its default configuration if build triggers and webhooks are set up correctly.

  By default, the Step performs a shallow clone in most cases (fetching only the latest commit) to make the clone fast and efficient. If your workflow requires a deeper commit history, you can override this using the **Clone depth** input.

  ### Useful links

  - [How to register a GitHub Enterprise repository](https://discuss.bitrise.io/t/how-to-register-a-github-enterprise-repository/218)
  - [Code security](https://devcenter.bitrise.io/getting-started/code-security/)

  ### Related Steps

  - [Activate SSH key (RSA private key)](https://www.bitrise.io/integrations/steps/activate-ssh-key)
  - [Generate changelog](https://bitrise.io/integrations/steps/generate-changelog)

website: https://github.com/bitrise-steplib/steps-git-clone
source_code_url: https://github.com/bitrise-steplib/steps-git-clone
support_url: https://github.com/bitrise-steplib/steps-git-clone/issues
type_tags:
- utility
is_requires_admin_user: false
is_always_run: false
is_skippable: false
run_if: .IsCI
toolkit:
  go:
    package_name: github.com/bitrise-steplib/steps-git-clone
inputs:
- merge_pr: "yes"
  opts:
    title: Checkout merged PR state
    summary: Checkout the merged PR state instead of the PR head
    description: |-
      This only applies to builds triggered by pull requests.

      Options:
      - `yes`: Depending on the information in the build trigger, either fetches the PR merge ref or creates the merged state locally.
      - `no`: Checks out the head of the PR branch without merging it into the destination branch.
    value_options:
    - "yes"
    - "no"

- git_http_username: $GIT_HTTP_USERNAME
  opts:
    title: Username for establishing an HTTP(S) connection to the repository
    is_dont_change_value: true
    is_sensitive: true

- git_http_password: $GIT_HTTP_PASSWORD
  opts:
    title: Personal access token (or password) for establishing an HTTP(S) connection to the repository
    is_dont_change_value: true
    is_sensitive: true

# Clone options
- clone_into_dir: $BITRISE_SOURCE_DIR
  opts:
    category: Clone options
    title: Clone destination directory
    description: Local directory where the repository is cloned
    is_required: true

- clone_depth:
  opts:
    category: Clone options
    title: Clone depth
    summary: Number of commits to fetch
    description: |-
      Limit fetching to the specified number of commits.

      By default, the Step tries to do a shallow clone (depth of 1) if it's possible based on the build trigger parameters. If it's not possible, it applies a low depth value, unless another value is specified here.

      It's not recommended to define this input because a shallow clone ensures fast clone times. Examples of when you want to override the clone depth:

      - A Step in the workflow reads the commit history in order to generate a changelog
      - A Step in the workflow runs a git diff against a previous commit

      Use the value `-1` to disable the depth limit completely and fetch the entire repo history.
- update_submodules: "yes"
  opts:
    category: Clone options
    title: Update submodules
    description: |-
      Update registered submodules to match what the superproject expects.
      If set to `no`, `git fetch` calls will use the `--no-recurse-submodules` flag.
    value_options:
    - "yes"
    - "no"

- submodule_update_depth:
  opts:
    category: Clone options
    title: Submodule update depth
    description: |-
      When updating submodules, limit fetching to the specified number of commits.
      The value should be a decimal number, for example `10`.

- fetch_tags: "no"
  opts:
    category: Clone options
    title: Fetch tags
    description: |-
      yes - fetch all tags from the remote by adding `--tags` flag to `git fetch` calls
      no - disable automatic tag following by adding `--no-tags` flag to `git fetch` calls
    value_options:
    - "yes"
    - "no"

- sparse_directories: ""
  opts:
    category: Clone options
    title: Sparse checkout directories
    description: |-
      Limit which directories to clone using [sparse-checkout](https://git-scm.com/docs/git-sparse-checkout). This is useful for monorepos where the current workflow only needs a subfolder.

      For example, specifying `src/android` the Step will only clone:
      - contents of the root directory and
      - contents of the `src/android` directory and all of its subdirectories
      On the other hand, `src/ios` will not be cloned.

      This input accepts one path per line, separate entries by a linebreak.

# Build trigger parameters

- repository_url: $GIT_REPOSITORY_URL
  opts:
    category: Build trigger parameters
    title: Git repository URL
    description: SSH or HTTPS URL of the repository to clone
    is_required: true
    is_dont_change_value: true

- commit: $BITRISE_GIT_COMMIT
  opts:
    category: Build trigger parameters
    title: Git commit to checkout
    description: Commit SHA to checkout
    is_dont_change_value: true
- tag: $BITRISE_GIT_TAG
  opts:
    category: Build trigger parameters
    title: Git tag
    description: Git tag to checkout
    is_dont_change_value: true

- branch: $BITRISE_GIT_BRANCH
  opts:
    category: Build trigger parameters
    title: Git branch
    description: Git branch to checkout
    is_dont_change_value: true

- branch_dest: $BITRISEIO_GIT_BRANCH_DEST
  opts:
    category: Build trigger parameters
    title: Pull request destination branch
    description: The branch that the pull request targets, such as `main`
    is_dont_change_value: true

- pull_request_repository_url: $BITRISEIO_PULL_REQUEST_REPOSITORY_URL
  opts:
    category: Build trigger parameters
    title: Pull request source repository
    summary: URL of the source repository of a pull request.
    description: |-
      URL of the source repository of a pull request.

      This points to the fork repository in builds triggered by pull requests.
    is_dont_change_value: true

- pull_request_merge_branch: $BITRISEIO_PULL_REQUEST_MERGE_BRANCH
  opts:
    category: Build trigger parameters
    title: Pull request merge ref
    description: |-
      Git ref pointing to the result of merging the PR branch into the destination branch. Even if the source of the PR is a fork, this is a reference to the destination repository.

      Example: `refs/pull/14/merge`

      Note: not all Git services provide this value.
    is_dont_change_value: true

- pull_request_unverified_merge_branch: $BITRISEIO_PULL_REQUEST_UNVERIFIED_MERGE_BRANCH
  opts:
    category: Build trigger parameters
    title: Unverified pull request merge ref
    description: |-
      This input is the same as **Pull request merge ref**, but the provided merge ref can be potentially outdated. The Step will make an attempt to check it's validity and only use it for the checkout if it's up-to-date with the PR head.
    is_dont_change_value: true

- pull_request_head_branch: $BITRISEIO_PULL_REQUEST_HEAD_BRANCH
  opts:
    category: Build trigger parameters
    title: Pull request head ref
    description: |-
      Git ref pointing to the head of the PR branch. Even if the source of the PR is a fork, this is a reference to the destination repository.

      Example: `refs/pull/14/head`

      Note: not all Git services provide this value.
    is_dont_change_value: true

# Debug

- reset_repository: "No"
  opts:
    category: Debug
    title: Reset repository
    summary: Reset repository before fetching.
    description: Reset repository contents with `git reset --hard HEAD` and `git clean -f` before fetching.
    value_options:
    - "No"
    - "Yes"

- build_url: $BITRISE_BUILD_URL
  opts:
    category: Debug
    title: Bitrise Build URL
    summary: |-
      Unique build URL of this build on Bitrise.io
    description: |-
      Unique build URL of this build on Bitrise.io
    is_dont_change_value: true

- build_api_token: $BITRISE_BUILD_API_TOKEN
  opts:
    category: Debug
    title: Bitrise Build API Token
    summary: |-
      The build's API Token for the build on Bitrise.io
    description: |-
      The build's API Token for the build on Bitrise.io
    is_dont_change_value: true
    is_sensitive: true

outputs:
- GIT_CLONE_COMMIT_HASH:
  opts:
    title: Commit hash
    description: SHA hash of the checked-out commit.
- GIT_CLONE_COMMIT_MESSAGE_SUBJECT:
  opts:
    title: Commit message subject
    description: Commit message of the checked-out commit.
- GIT_CLONE_COMMIT_MESSAGE_BODY:
  opts:
    title: Commit message body
    description: Commit message body of the checked-out commit.
- GIT_CLONE_COMMIT_COUNT:
  opts:
    title: Commit count
    description: |-
      Commit count after checkout.

      Count will only work properly if no `--depth` option is set. If `--depth` is set then the history truncated to the specified number of commits. Count will **not** fail but will be the clone depth.
- GIT_CLONE_COMMIT_AUTHOR_NAME:
  opts:
    title: Commit author name
    description: Author of the checked-out commit.
- GIT_CLONE_COMMIT_AUTHOR_EMAIL:
  opts:
    title: Commit author email
    description: Email of the checked-out commit.
- GIT_CLONE_COMMIT_COMMITTER_NAME:
  opts:
    title: Committer name
    description: Committer name of the checked-out commit.
- GIT_CLONE_COMMIT_COMMITTER_EMAIL:
  opts:
    title: Committer email
    description: Email of the checked-out commit.