docs(pipelines): explain how to retain symlinks (#20413)

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

packages/@aws-cdk/pipelines/lib/codepipeline/codepipeline-source.ts

@@ -38,6 +38,9 @@ export abstract class CodePipelineSource extends Step implements ICodePipelineAc
    *
    * * **repo** - to read the repository
    * * **admin:repo_hook** - if you plan to use webhooks (true by default)
+   *
+   * If you need access to symlinks or the repository history, use a source of type
+   * `connection` instead.
    */
   public static gitHub(repoString: string, branch: string, props: GitHubSourceOptions = {}): CodePipelineSource {
     return new GitHubSource(repoString, branch, props);
@@ -92,6 +95,9 @@ export abstract class CodePipelineSource extends Step implements ICodePipelineAc
    * });
    * ```
    *
+   * If you need access to symlinks or the repository history, be sure to set
+   * `codeBuildCloneOutput`.
+   *
    * @param repoString A string that encodes owner and repository separated by a slash (e.g. 'owner/repo').
    * @param branch The branch to use.
    * @param props The source properties, including the connection ARN.
@@ -105,6 +111,10 @@ export abstract class CodePipelineSource extends Step implements ICodePipelineAc
   /**
    * Returns a CodeCommit source.
    *
+   * If you need access to symlinks or the repository history, be sure to set
+   * `codeBuildCloneOutput`.
+   *
+   *
    * @param repository The CodeCommit repository.
    * @param branch The branch to use.
    * @param props The source properties.
@@ -360,12 +370,12 @@ export interface ConnectionSourceOptions {
 
   // long URL in @see
   /**
-   * Whether the output should be the contents of the repository
-   * (which is the default),
-   * or a link that allows CodeBuild to clone the repository before building.
+   * If this is set, the next CodeBuild job clones the repository (instead of CodePipeline downloading the files).
+   *
+   * This provides access to repository history, and retains symlinks (symlinks would otherwise be
+   * removed by CodePipeline).
    *
-   * **Note**: if this option is true,
-   * then only CodeBuild actions can use the resulting {@link output}.
+   * **Note**: if this option is true, only CodeBuild jobs can use the output artifact.
    *
    * @default false
    * @see https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-CodestarConnectionSource.html#action-reference-CodestarConnectionSource-config
@@ -435,12 +445,12 @@ export interface CodeCommitSourceOptions {
   readonly eventRole?: iam.IRole;
 
   /**
-   * Whether the output should be the contents of the repository
-   * (which is the default),
-   * or a link that allows CodeBuild to clone the repository before building.
+   * If this is set, the next CodeBuild job clones the repository (instead of CodePipeline downloading the files).
+   *
+   * This provides access to repository history, and retains symlinks (symlinks would otherwise be
+   * removed by CodePipeline).
    *
-   * **Note**: if this option is true,
-   * then only CodeBuild actions can use the resulting {@link output}.
+   * **Note**: if this option is true, only CodeBuild jobs can use the output artifact.
    *
    * @default false
    * @see https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-CodeCommit.html