From 35326a84a78d4630e39f171edfd8453dde6de20b Mon Sep 17 00:00:00 2001 From: LizGaudet <100166887+LizGaudet@users.noreply.github.com> Date: Mon, 27 Jan 2025 12:18:30 -0500 Subject: [PATCH 1/4] Update README.adoc --- README.adoc | 375 ++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 333 insertions(+), 42 deletions(-) diff --git a/README.adoc b/README.adoc index 695c0c2..fed6679 100644 --- a/README.adoc +++ b/README.adoc @@ -4,9 +4,29 @@ Use this action to check out a Git repository under `+$CLOUDBEES_WORKSPACE+`, to 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. +The CloudBees API token is used to fetch an app access token if neither a personal access token (PAT) nor an SSH key are provided. -== Inputs +[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. +==== + +Check out a repository from any of the following source code management (SCM) providers: + +* link:https://github.com/cloudbees-io/checkout/main/README.adoc#bitbucket-repository-check-out[Bitbucket] +* link:https://github.com/cloudbees-io/checkout/main/README.adoc#github-repository-check-out[GitHub] +* xref:README.adoc#gitlab-repository-check-out[GitLab] + +== Bitbucket repository check out + +Use this action to check out a Bitbucket repository. + +=== Required inputs + +The following inputs are required for using this action with a Bitbucket repository. [cols="2a,1a,1a,4a",options="header"] .Input details @@ -20,13 +40,37 @@ The CloudBees API token is used to fetch an app access token if neither the PAT | `provider` | String | Yes -| SCM provider hosting the repository, such as GitHub, Bitbucket, or GitLab. +| SCM provider hosting the repository. Specify `bitbucket`. | `repository` | String | Yes | Repository name with owner, for example, `actions/checkout`. +| `bitbucket-server-url` +| String +| Yes +| The base URL for the Bitbucket instance that you are cloning from. +Unless specified, the base URL uses environment defaults to fetch from the same instance the workflow is running from. +Example URLs are `\https://bitbucket.org` or `\https://my-bbdc-server.example.com`. + +|=== + +=== Optional inputs + +.The following inputs are available, but not required, to use in this action. +[.collapsible] +-- + +[cols="2a,1a,1a,4a",options="header"] +.Optional input details +|=== + +| Input name +| Data type +| Required? +| Description + | `ref` | String | No @@ -35,9 +79,9 @@ The action uses your default branch, unless you check out a repository that trig | `token` | String -| No +| 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. +The PAT is configured with the local Git config, which enables your scripts to run authenticated Git commands. | `ssh-key` | String @@ -98,19 +142,198 @@ When the `ssh-key` input is not provided, SSH URLs beginning with `git@github.co | 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 `. +|=== + +-- + +=== Usage example + +The following example uses this action to check out the `test` branch of a Bitbucket repository, using a PAT. + +[source,yaml] +---- + - name: Check out Bitbucket repo + uses: 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_PAT }} + +---- + +== GitHub repository check out + +Use this action to check out a GitHub repository. + +=== Required inputs + +The following inputs are required for using this action with a GitHub repository. + +[cols="2a,1a,1a,4a",options="header"] +.Input details +|=== + +| Input name +| Data type +| Required? +| Description + +| `provider` +| String +| Yes +| SCM provider hosting the repository. Specify `github`. + +| `repository` +| String +| Yes +| Repository name with owner, for example, `actions/checkout`. + | `github-server-url` | String -| No +| Yes | The base URL for the GitHub instance that you are cloning from. Unless specified, the base URL uses environment defaults to fetch from the same instance the workflow is running from. Example URLs are `\https://github.com` or `\https://my-ghes-server.example.com`. -| `bitbucket-server-url` +|=== + +=== Optional inputs + +.The following inputs are available, but not required, to use in this action. +[.collapsible] +-- + +[cols="2a,1a,1a,4a",options="header"] +.Optional input details +|=== + +| Input name +| Data type +| Required? +| Description + +| `ref` | String | No -| The base URL for the Bitbucket instance that you are cloning from. -Unless specified, the base URL uses environment defaults to fetch from the same instance the workflow is running from. -Example URLs are `\https://bitbucket.org` or `\https://my-bbdc-server.example.com`. +| The branch, tag or SHA to check out. +The action uses your default branch, unless you check out a repository that triggered a workflow, in which case it defaults to the reference or SHA for that event. + +| `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. + +| `ssh-key` +| String +| No +| SSH key used to fetch the repository. +The SSH key is configured with the local Git config, which enables your scripts to run authenticated Git commands. + +| `ssh-known-hosts` +| String +| No +| Known hosts in addition to the user and global host key database. +Use the utility `ssh-keyscan` to get public SSH keys for a host. +For example, use `ssh-keyscan my-ssh-server.example.com` to get the keys for your self-hosted SSH server at `my-ssh-server.example.com`. +The public keys for GitHub, Bitbucket, and GitLab are already 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. + +| `persist-credentials` +| Boolean +| No +| Default is `true`. When `true`, the token or SSH key is configured with the local Git config. + +| `path` +| String +| No +| The relative path to place the repository under `$CLOUDBEES_WORKSPACE`. + +| `clean` +| Boolean +| No +| Default is `true`. When `true`, executes `git clean -ffdx && git reset --hard HEAD` before fetching. + +| `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. + +| `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. + +| `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 `. + +|=== + +-- + +=== Usage example + +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. + +[source,yaml] +---- + - name: Check out GitHub repo + uses: cloudbees-io/checkout@v1 + with: + provider: github + repository: 'my-name/my-repo-name' + github-server-url: 'https://github.com' + ssh-key: {{ secrets.MY_SSH_KEY }} + persist-credentials: false + fetch-depth: 0 + +---- + +== GitLab repository check out + +Use this action to check out a GitLab repository. + +=== Inputs + +The following inputs are required for using this action with a GitLab repository. + +[cols="2a,1a,1a,4a",options="header"] +.Input details +|=== + +| Input name +| Data type +| Required? +| Description + +| `provider` +| String +| Yes +| SCM provider hosting the repository. Specify `gitlab`. + +| `repository` +| String +| Yes +| Repository name with owner, for example, `actions/checkout`. | `gitlab-server-url` | String @@ -120,42 +343,114 @@ Unless specified, the base URL uses environment defaults to fetch from the same Example URLs are `\https://gitlab.com` or `\https://my-gl-server.example.com`. |=== -== Usage example +=== Optional inputs -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. +.The following inputs are available, but not required, to use in this action. +[.collapsible] +-- -[NOTE] -==== -CloudBees recommends: +[cols="2a,1a,1a,4a",options="header"] +.Optional input details +|=== -* Use a service account that limits user access to only necessary permissions. -* When generating a new PAT, select the narrowest possible scope. -==== +| Input name +| Data type +| Required? +| Description -In your YAML file, add: +| `ref` +| String +| No +| The branch, tag or SHA to check out. +The action uses your default branch, unless you check out a repository that triggered a workflow, in which case it defaults to the reference or SHA for that event. -[source,yaml] +| `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. + +| `ssh-key` +| String +| No +| SSH key used to fetch the repository. +The SSH key is configured with the local Git config, which enables your scripts to run authenticated Git commands. + +| `ssh-known-hosts` +| String +| No +| Known hosts in addition to the user and global host key database. +Use the utility `ssh-keyscan` to get public SSH keys for a host. +For example, use `ssh-keyscan my-ssh-server.example.com` to get the keys for your self-hosted SSH server at `my-ssh-server.example.com`. +The public keys for GitHub, Bitbucket, and GitLab are already 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. + +| `persist-credentials` +| Boolean +| No +| Default is `true`. When `true`, the token or SSH key is configured with the local Git config. + +| `path` +| String +| No +| The relative path to place the repository under `$CLOUDBEES_WORKSPACE`. + +| `clean` +| Boolean +| No +| Default is `true`. When `true`, executes `git clean -ffdx && git reset --hard HEAD` before fetching. + +| `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. + +| `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. + +| `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 `. + +|=== + +-- + +=== Usage example + +The following example uses this action to check out the last commit of the default branch of a GitLab repository, using the CloudBees API token. +Submodules are recursively checked out. + +[source,yaml,role="default-expanded"] ---- - - name: Check out repo + - name: Check out GitLab repo uses: cloudbees-io/checkout@v1 with: - provider: ${{ cloudbees.scm.provider }} - repository: ${{ cloudbees.repository }} - ref: '' + provider: 'gitlab' + repository: 'my_name/my_repo' + gitlab-server-url: 'https://my-gl-server.example.com' token: ${{ cloudbees.scm.token }} - ssh-key: '' - ssh-known-hosts: '' - ssh-strict: true - persist-credentials: true - path: '' - clean: true + path: 'my_path' fetch-depth: 1 - lfs: false - submodules: false - set-safe-directory: true - github-server-url: '' - bitbucket-server-url: '' - gitlab-server-url: '' + submodules: 'recursive' + ---- == License @@ -165,9 +460,5 @@ link:https://opensource.org/license/mit/[MIT license]. == References -* Learn more about link:https://docs.cloudbees.com/docs/cloudbees-saas-platform-actions/latest/[using actions in CloudBees workflows]. -* Learn about link:https://docs.cloudbees.com/docs/cloudbees-saas-platform/latest/[the CloudBees platform]. - - - - +* Learn more about link:https://docs.cloudbees.com/docs/cloudbees-platform/latest/actions[using actions in CloudBees workflows]. +* Learn about link:https://docs.cloudbees.com/docs/cloudbees-platform/latest/[the CloudBees platform]. From 3cfb9fb3d9cb6b851a9a4bc26c1384eac47f125c Mon Sep 17 00:00:00 2001 From: LizGaudet <100166887+LizGaudet@users.noreply.github.com> Date: Mon, 27 Jan 2025 12:20:49 -0500 Subject: [PATCH 2/4] Update README.adoc --- README.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.adoc b/README.adoc index fed6679..a299020 100644 --- a/README.adoc +++ b/README.adoc @@ -16,8 +16,8 @@ CloudBees recommends: Check out a repository from any of the following source code management (SCM) providers: -* link:https://github.com/cloudbees-io/checkout/main/README.adoc#bitbucket-repository-check-out[Bitbucket] -* link:https://github.com/cloudbees-io/checkout/main/README.adoc#github-repository-check-out[GitHub] +* xref:README.adoc#bitbucket-repository-check-out[Bitbucket] +* xref:README.adoc#github-repository-check-out[GitHub] * xref:README.adoc#gitlab-repository-check-out[GitLab] == Bitbucket repository check out From 8ec7d50d13db85d93104b1a672d6fb476415994a Mon Sep 17 00:00:00 2001 From: LizGaudet <100166887+LizGaudet@users.noreply.github.com> Date: Mon, 27 Jan 2025 12:25:54 -0500 Subject: [PATCH 3/4] Update README.adoc --- README.adoc | 224 ++++++---------------------------------------------- 1 file changed, 24 insertions(+), 200 deletions(-) diff --git a/README.adoc b/README.adoc index a299020..d00eaae 100644 --- a/README.adoc +++ b/README.adoc @@ -58,93 +58,7 @@ Example URLs are `\https://bitbucket.org` or `\https://my-bbdc-server.example.co === Optional inputs -.The following inputs are available, but not required, to use in this action. -[.collapsible] --- - -[cols="2a,1a,1a,4a",options="header"] -.Optional input details -|=== - -| Input name -| Data type -| Required? -| Description - -| `ref` -| String -| No -| The branch, tag or SHA to check out. -The action uses your default branch, unless you check out a repository that triggered a workflow, in which case it defaults to the reference or SHA for that event. - -| `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. - -| `ssh-key` -| String -| No -| SSH key used to fetch the repository. -The SSH key is configured with the local Git config, which enables your scripts to run authenticated Git commands. - -| `ssh-known-hosts` -| String -| No -| Known hosts in addition to the user and global host key database. -Use the utility `ssh-keyscan` to get public SSH keys for a host. -For example, use `ssh-keyscan my-ssh-server.example.com` to get the keys for your self-hosted SSH server at `my-ssh-server.example.com`. -The public keys for GitHub, Bitbucket, and GitLab are already 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. - -| `persist-credentials` -| Boolean -| No -| Default is `true`. When `true`, the token or SSH key is configured with the local Git config. - -| `path` -| String -| No -| The relative path to place the repository under `$CLOUDBEES_WORKSPACE`. - -| `clean` -| Boolean -| No -| Default is `true`. When `true`, executes `git clean -ffdx && git reset --hard HEAD` before fetching. - -| `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. - -| `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. - -| `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 `. - -|=== - --- +Refer to xref:README#optional-inputs[optional inputs] for other inputs available for use in this action. === Usage example @@ -201,93 +115,7 @@ Example URLs are `\https://github.com` or `\https://my-ghes-server.example.com`. === Optional inputs -.The following inputs are available, but not required, to use in this action. -[.collapsible] --- - -[cols="2a,1a,1a,4a",options="header"] -.Optional input details -|=== - -| Input name -| Data type -| Required? -| Description - -| `ref` -| String -| No -| The branch, tag or SHA to check out. -The action uses your default branch, unless you check out a repository that triggered a workflow, in which case it defaults to the reference or SHA for that event. - -| `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. - -| `ssh-key` -| String -| No -| SSH key used to fetch the repository. -The SSH key is configured with the local Git config, which enables your scripts to run authenticated Git commands. - -| `ssh-known-hosts` -| String -| No -| Known hosts in addition to the user and global host key database. -Use the utility `ssh-keyscan` to get public SSH keys for a host. -For example, use `ssh-keyscan my-ssh-server.example.com` to get the keys for your self-hosted SSH server at `my-ssh-server.example.com`. -The public keys for GitHub, Bitbucket, and GitLab are already 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. - -| `persist-credentials` -| Boolean -| No -| Default is `true`. When `true`, the token or SSH key is configured with the local Git config. - -| `path` -| String -| No -| The relative path to place the repository under `$CLOUDBEES_WORKSPACE`. - -| `clean` -| Boolean -| No -| Default is `true`. When `true`, executes `git clean -ffdx && git reset --hard HEAD` before fetching. - -| `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. - -| `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. - -| `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 `. - -|=== - --- +Refer to xref:README#optional-inputs[optional inputs] for other inputs available for use in this action. === Usage example @@ -343,11 +171,29 @@ Unless specified, the base URL uses environment defaults to fetch from the same Example URLs are `\https://gitlab.com` or `\https://my-gl-server.example.com`. |=== -=== Optional inputs +=== Usage example + +The following example uses this action to check out the last commit of the default branch of a GitLab repository, using the CloudBees API token. +Submodules are recursively checked out. + +[source,yaml,role="default-expanded"] +---- + - name: Check out GitLab repo + uses: cloudbees-io/checkout@v1 + with: + provider: 'gitlab' + repository: 'my_name/my_repo' + gitlab-server-url: 'https://my-gl-server.example.com' + token: ${{ cloudbees.scm.token }} + path: 'my_path' + fetch-depth: 1 + submodules: 'recursive' + +---- -.The following inputs are available, but not required, to use in this action. -[.collapsible] --- +== Optional inputs + +The following inputs are available, but not required, to use in this action with any SCM provider. [cols="2a,1a,1a,4a",options="header"] .Optional input details @@ -431,28 +277,6 @@ When the `ssh-key` input is not provided, SSH URLs beginning with `git@github.co |=== --- - -=== Usage example - -The following example uses this action to check out the last commit of the default branch of a GitLab repository, using the CloudBees API token. -Submodules are recursively checked out. - -[source,yaml,role="default-expanded"] ----- - - name: Check out GitLab repo - uses: cloudbees-io/checkout@v1 - with: - provider: 'gitlab' - repository: 'my_name/my_repo' - gitlab-server-url: 'https://my-gl-server.example.com' - token: ${{ cloudbees.scm.token }} - path: 'my_path' - fetch-depth: 1 - submodules: 'recursive' - ----- - == License This code is made available under the From 61ca9b2b341f4660c569485049531d3badd8c1bb Mon Sep 17 00:00:00 2001 From: LizGaudet <100166887+LizGaudet@users.noreply.github.com> Date: Mon, 27 Jan 2025 12:27:21 -0500 Subject: [PATCH 4/4] Update README.adoc --- README.adoc | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.adoc b/README.adoc index d00eaae..bd55903 100644 --- a/README.adoc +++ b/README.adoc @@ -56,7 +56,7 @@ Example URLs are `\https://bitbucket.org` or `\https://my-bbdc-server.example.co |=== -=== Optional inputs +=== Non-required inputs Refer to xref:README#optional-inputs[optional inputs] for other inputs available for use in this action. @@ -113,7 +113,7 @@ Example URLs are `\https://github.com` or `\https://my-ghes-server.example.com`. |=== -=== Optional inputs +=== Non-required inputs Refer to xref:README#optional-inputs[optional inputs] for other inputs available for use in this action. @@ -171,6 +171,10 @@ Unless specified, the base URL uses environment defaults to fetch from the same Example URLs are `\https://gitlab.com` or `\https://my-gl-server.example.com`. |=== +=== Non-required inputs + +Refer to xref:README#optional-inputs[optional inputs] for other inputs available for use in this action. + === Usage example The following example uses this action to check out the last commit of the default branch of a GitLab repository, using the CloudBees API token.