docs: split up steps into separate reference pages

docs/docs/60-new-docs/60-user-guide/60-reference-docs/15-promotion-templates.md

@@ -0,0 +1,9 @@
+---
+sidebar_label: Promotion Templates
+---
+
+# Promotion Templates Reference
+
+:::warning
+Hidde to put something here by the end of the week
+:::

docs/docs/60-new-docs/60-user-guide/60-reference-docs/20-expressions.md

@@ -2,7 +2,7 @@
 sidebar_label: Expression Language
 ---
 
-# Kargo's Expression Language Reference
+# Expression Language Reference
 
 :::warning
 Hidde to put something here by the end of the week

docs/docs/60-new-docs/60-user-guide/60-reference-docs/30-promotion-steps/10-git-clone.md

@@ -0,0 +1,100 @@
+---
+sidebar_label: git-clone
+description: Clones a remote Git repository and checks out specified revisions to working trees at specified paths.
+---
+
+# `git-clone`
+
+`git-clone` is often the first step in a promotion process. It creates a
+[bare clone](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt-code--barecode)
+of a remote Git repository, then checks out one or more branches, tags, or
+commits to working trees at specified paths. Checking out different revisions to
+different paths is useful for the common scenarios of combining content from
+multiple sources or rendering Stage-specific manifests to a Stage-specific
+branch.
+
+:::note
+It is a noteworthy limitation of Git that one branch cannot be checked out in
+multiple working trees.
+:::
+
+## Configuration
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `repoURL` | `string` | Y | The URL of a remote Git repository to clone. |
+| `insecureSkipTLSVerify` | `boolean` | N | Whether to bypass TLS certificate verification when cloning (and for all subsequent operations involving this clone). Setting this to `true` is highly discouraged in production. |
+| `checkout` | `[]object` | Y | The commits, branches, or tags to check out from the repository and the paths where they should be checked out. At least one must be specified. |
+| `checkout[].branch` | `string` | N | A branch to check out. Mutually exclusive with `commit`, `tag`, and `fromFreight=true`. If none of these is specified, the default branch will be checked out. |
+| `checkout[].create` | `boolean` | N | In the event `branch` does not already exist on the remote, whether a new, empty, orphaned branch should be created. Default is `false`, but should commonly be set to `true` for Stage-specific branches, which may not exist yet at the time of a Stage's first promotion. |
+| `checkout[].commit` | `string` | N | A specific commit to check out. Mutually exclusive with `branch`, `tag`, and `fromFreight=true`. If none of these is specified, the default branch will be checked out. |
+| `checkout[].tag` | `string` | N | A tag to check out. Mutually exclusive with `branch`, `commit`, and `fromFreight=true`. If none of these is specified, the default branch will be checked out. |
+| `checkout[].fromFreight` | `boolean` | N | Whether a commit to check out should be obtained from the Freight being promoted. A value of `true` is mutually exclusive with `branch`, `commit`, and `tag`. If none of these is specified, the default branch will be checked out. Default is `false`, but is often set to `true`. <br/><br/>__Deprecated: Use `commit` with an expression instead. Will be removed in v1.3.0.__ |
+| `checkout[].fromOrigin` | `object` | N | See [specifying origins](#specifying-origins). <br/><br/>__Deprecated: Use `commit` with an expression instead. Will be removed in v1.3.0.__ |
+| `checkout[].path` | `string` | Y | The path for a working tree that will be created from the checked out revision. This path is relative to the temporary workspace that Kargo provisions for use by the promotion process. |
+
+## Examples
+
+### Common Usage
+
+The most common usage of this step is to check out a commit specified by the
+Freight being promoted as well as a Stage-specific branch. Subsequent steps are
+likely to perform actions that revise the contents of the Stage-specific branch
+using the commit from the Freight as input.
+
+```yaml
+vars:
+- name: gitRepo
+  value: https://github.com/example/repo.git
+steps:
+- uses: git-clone
+  config:
+    repoURL: ${{ vars.gitRepo }}
+    checkout:
+    - commit: ${{ commitFrom(vars.gitRepo) }}
+      path: ./src
+    - branch: stage/${{ ctx.stage }}
+      create: true
+      path: ./out
+# Prepare the contents of ./out ...
+# Commit, push, etc...
+```
+
+### Combining Multiple Sources
+
+For this more advanced example, consider a Stage that requests Freight from two
+Warehouses, where one provides Kustomize "base" configuration, while the other
+provides a Stage-specific Kustomize overlay. Rendering the manifests intended
+for such a Stage will require combining the base and overlay configurations
+with the help of a [`copy`](20-copy.md) step. For this case, a `git-clone` step
+may be configured similarly to the following:
+
+```yaml
+vars:
+- name: gitRepo
+  value: https://github.com/example/repo.git
+steps:
+- uses: git-clone
+  config:
+    repoURL: ${{ vars.gitRepo }}
+    checkout:
+    - commit: ${{ commitFrom(vars.gitRepo, warehouse("base")).ID }}
+      path: ./src
+    - commit: ${{ commitFrom(vars.gitRepo, warehouse(ctx.stage + "-overlay")).ID }}
+      path: ./overlay
+    - branch: stage/${{ ctx.stage }}
+      create: true
+      path: ./out
+- uses: git-clear
+  config:
+    path: ./out
+- uses: copy
+  config:
+    inPath: ./overlay/stages/${{ ctx.stage }}/kustomization.yaml
+    outPath: ./src/stages/${{ ctx.stage }}/kustomization.yaml
+- uses: kustomize-build
+  config:
+    path: ./src/stages/${{ ctx.stage }}
+    outPath: ./out
+# Commit, push, etc...
+```

docs/docs/60-new-docs/60-user-guide/60-reference-docs/30-promotion-steps/11-git-clear.md

@@ -0,0 +1,37 @@
+---
+sidebar_label: git-clear
+description: Deletes the entire contents of a specified Git working tree.
+---
+
+# `git-clear`
+
+`git-clear` deletes _the entire contents_ of a specified Git working tree
+(except for the `.git` file). It is equivalent to executing
+`git add . && git rm -rf --ignore-unmatch .`. This step is useful for the common
+scenario where the entire content of a Stage-specific branch is to be replaced
+with content from another branch or with content rendered using some
+configuration management tool.
+
+## Configuration
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | `string` | Y | Path to a Git working tree whose entire contents are to be deleted. |
+
+## Examples
+
+```yaml
+steps:
+- uses: git-clone
+  config:
+    repoURL: https://github.com/example/repo.git
+    checkout:
+    - branch: stage/${{ ctx.stage }}
+      create: true
+      path: ./out
+- uses: git-clear
+  config:
+    path: ./out
+# Prepare the contents of ./out ...
+# Commit, push, etc...
+```

docs/docs/60-new-docs/60-user-guide/60-reference-docs/30-promotion-steps/15-git-commit.md

@@ -0,0 +1,63 @@
+---
+sidebar_label: git-commit
+description: Commits all changes in a working tree to its checked out branch.
+---
+
+# `git-commit`
+
+`git-commit` commits all changes in a working tree to its checked out branch.
+This step is often used after previous steps have put the working tree into the
+desired state and is commonly followed by a [`git-push` step](16-git-push.md).
+
+## Configuration
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | `string` | Y | Path to a Git working tree containing changes to be committed. This path is relative to the temporary workspace that Kargo provisions for use by the promotion process. |
+| `message` | `string` | N | The commit message. Mutually exclusive with `messageFromSteps`. |
+| `messageFromSteps` | `[]string` | N | References the `commitMessage` output of previous steps. When one or more are specified, the commit message will be constructed by concatenating the messages from individual steps. Mutually exclusive with `message`. |
+| `author` | `[]object` | N | Optionally provider authorship information for the commit. |
+| `author.name` | `string` | N | The committer's name. |
+| `author.email` | `string` | N | The committer's email address. |
+
+## Output
+
+| Name | Type | Description |
+|------|------|-------------|
+| `commit` | `string` | The ID (SHA) of the commit created by this step. If the step short-circuited and did not create a new commit because there were no differences from the current head of the branch, this value will be the ID of the existing commit at the head of the branch instead. Typically, a subsequent [`argocd-update`](50-argocd-update.md) step will reference this output to learn the ID of the commit that an applicable Argo CD `ApplicationSource` should be observably synced to under healthy conditions. |
+
+## Examples
+
+```yaml
+vars:
+- name: gitRepo
+  value: https://github.com/example/repo.git
+steps:
+- uses: git-clone
+  config:
+    repoURL: ${{ vars.gitRepo }}
+    checkout:
+    - commit: ${{ commitFrom(vars.gitRepo).ID }}
+      path: ./src
+    - branch: stage/${{ ctx.stage }}
+      create: true
+      path: ./out
+- uses: git-clear
+  config:
+    path: ./out
+- uses: kustomize-set-image
+  as: update-image
+  config:
+    images:
+    - image: my/image
+- uses: kustomize-build
+  config:
+    path: ./src/stages/${{ ctx.stage }}
+    outPath: ./out
+- uses: git-commit
+  config:
+    path: ./out
+    messageFromSteps:
+    - update-image
+# Push, etc...
+```

docs/docs/60-new-docs/60-user-guide/60-reference-docs/30-promotion-steps/16-git-push.md

@@ -0,0 +1,76 @@
+---
+sidebar_label: git-push
+description: Pushes the committed changes in a specified working tree to a specified branch in the remote repository.
+---
+
+# `git-push`
+
+`git-push` pushes the committed changes in a specified working tree to a
+specified branch in the remote repository. This step typically follows a
+[`git-commit` step](15-git-commit.md) and is often followed by a
+[`git-open-pr` step](18-git-open-pr.md).
+
+This step also implements its own, internal retry logic. If a push fails, with
+the cause determined to be the presence of new commits in the remote branch that
+are not present in the local branch, the step will attempt to rebase before
+retrying the push. Any merge conflict requiring manual resolution will
+immediately halt further attempts.
+
+:::info
+This step's internal retry logic is helpful in scenarios when concurrent
+Promotions to multiple Stages may all write to the same branch of the same
+repository.
+
+Because conflicts requiring manual resolution will halt further attempts, it is
+recommended to design your Promotion processes such that Promotions to multiple
+Stages that write to the same branch do not write to the same files.
+:::
+
+## Configuration
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | `string` | Y | Path to a Git working tree containing committed changes. |
+| `targetBranch` | `string` | N | The branch to push to in the remote repository. Mutually exclusive with `generateTargetBranch=true`. If neither of these is provided, the target branch will be the same as the branch currently checked out in the working tree. |
+| `maxAttempts` | `int32` | N | The maximum number of attempts to make when pushing to the remote repository. Default is 50. |
+| `generateTargetBranch` | `boolean` | N | Whether to push to a remote branch named like `kargo/<project>/<stage>/promotion`. If such a branch does not already exist, it will be created. A value of 'true' is mutually exclusive with `targetBranch`. If neither of these is provided, the target branch will be the currently checked out branch. This option is useful when a subsequent promotion step will open a pull request against a Stage-specific branch. In such a case, the generated target branch pushed to by the `git-push` step can later be utilized as the source branch of the pull request. |
+
+## Output
+
+| Name | Type | Description |
+|------|------|-------------|
+| `branch` | `string` | The name of the remote branch pushed to by this step. This is especially useful when the `generateTargetBranch=true` option has been used, in which case a subsequent [`git-open-pr`](18-git-open-pr.md) will typically reference this output to learn what branch to use as the head branch of a new pull request. |
+| `commit` | `string` | The ID (SHA) of the commit pushed by this step. |
+
+## Examples
+
+### Common Usage
+
+```yaml
+steps:
+# Clone, prepare the contents of ./out, etc...
+- uses: git-commit
+  config:
+    path: ./out
+    message: rendered updated manifests
+- uses: git-push
+  config:
+    path: ./out
+```
+
+### For Use With a Pull Request
+
+```yaml
+steps:
+# Clone, prepare the contents of ./out, etc...
+- uses: git-commit
+  config:
+    path: ./out
+    message: rendered updated manifests
+- uses: git-push
+  as: push
+  config:
+    path: ./out
+    generateTargetBranch: true
+# Open a PR and wait for it to be merged or closed...
+```

docs/docs/60-new-docs/60-user-guide/60-reference-docs/30-promotion-steps/18-git-open-pr.md

@@ -0,0 +1,54 @@
+---
+sidebar_label: git-open-pr
+description: Opens a pull request in a specified remote repository using specified source and target branches.
+---
+
+# `git-open-pr`
+
+`git-open-pr` opens a pull request in a specified remote repository using
+specified source and target branches. This step is often used after a
+[`git-push` step](16-git-push.md) and is commonly followed by a
+[`git-wait-for-pr` step](19-git-wait-for-pr.md).
+
+At present, this feature only supports GitHub pull requests and GitLab merge
+requests.
+
+## Configuration
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `repoURL` | `string` | Y | The URL of a remote Git repository. |
+| `provider` | `string` | N | The name of the Git provider to use. Currently only `github` and `gitlab` are supported. Kargo will try to infer the provider if it is not explicitly specified.  |
+| `insecureSkipTLSVerify` | `boolean` | N | Indicates whether to bypass TLS certificate verification when interfacing with the Git provider. Setting this to `true` is highly discouraged in production. |
+| `sourceBranch` | `string` | N | Specifies the source branch for the pull request. Mutually exclusive with `sourceBranchFromStep`. |
+| `sourceBranchFromStep` | `string` | N | Indicates the source branch should be determined by the `branch` key in the output of a previous promotion step with the specified alias. Mutually exclusive with `sourceBranch`.<br/><br/>__Deprecated: Use `sourceBranch` with an expression instead. Will be removed in v1.3.0.__  |
+| `targetBranch` | `string` | N | The branch to which the changes should be merged. |
+| `createTargetBranch` | `boolean` | N | Indicates whether a new, empty orphaned branch should be created and pushed to the remote if the target branch does not already exist there. Default is `false`. |
+| `title` | `string` | N | The title for the pull request. Kargo generates a title based on the commit messages if it is not explicitly specified. |
+| `labels` | `[]string` | N | Labels to add to the pull request. |
+
+## Output
+
+| Name | Type | Description |
+|------|------|-------------|
+| `prNumber` | `number` | The numeric identifier of the pull request opened by this step. Typically, a subsequent [`git-wait-for-pr` step](19-git-wait-for-pr.md) will reference this output to learn what pull request to monitor. |
+
+## Examples
+
+```yaml
+steps:
+# Clone, prepare the contents of ./out, commit, etc...
+- uses: git-push
+  as: push
+  config:
+    path: ./out
+    generateTargetBranch: true
+- uses: git-open-pr
+  as: open-pr
+  config:
+    repoURL: https://github.com/example/repo.git
+    createTargetBranch: true
+    sourceBranch: ${{ outputs.push.branch }}
+    targetBranch: stage/${{ ctx.stage }}
+# Wait for the PR to be merged or closed...
+```