From 815b124415907f042691f730d1fffd3e4d48c4b7 Mon Sep 17 00:00:00 2001 From: Trent Mohay Date: Wed, 3 Jun 2026 13:54:14 +1000 Subject: [PATCH 1/2] docs(deployments): add Commit to Git step page Document the new Commit to Git built-in step under a new Deployments > Git area. Covers the destination repository, commit message, commit method, input files, optional script, step verification, execution flow, and output variables, plus the Early Access caveats around credential types and pull request support. Co-Authored-By: Claude Opus 4.8 (1M context) --- dictionary-octopus.txt | 1 + .../docs/deployments/git/commit-to-git.md | 119 ++++++++++++++++++ src/pages/docs/deployments/git/index.md | 14 +++ 3 files changed, 134 insertions(+) create mode 100644 src/pages/docs/deployments/git/commit-to-git.md create mode 100644 src/pages/docs/deployments/git/index.md diff --git a/dictionary-octopus.txt b/dictionary-octopus.txt index 05c46d8af5..d3f9b3afca 100644 --- a/dictionary-octopus.txt +++ b/dictionary-octopus.txt @@ -525,6 +525,7 @@ struct stylesheet subcomponent subcontext +subfolders sunsetting swaggerui systemprofile diff --git a/src/pages/docs/deployments/git/commit-to-git.md b/src/pages/docs/deployments/git/commit-to-git.md new file mode 100644 index 0000000000..6cde6df9d6 --- /dev/null +++ b/src/pages/docs/deployments/git/commit-to-git.md @@ -0,0 +1,119 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-06-03 +modDate: 2026-06-03 +title: Commit to Git +description: Commit packages and files to a Git repository as part of your deployment process. +navOrder: 10 +--- + +The **Commit to Git** step commits packages and files to a Git repository as part of your deployment process. You can copy files from packages and other Git repositories into a target repository, optionally transform them with a script, and then commit the changes directly or through a pull request. + +The step brings together two behaviors you may already know from other steps: it accepts multiple input packages, like the [Deploy a Helm Chart](/docs/deployments/kubernetes/helm-update) step, and it can run a script over those files, like the [Run a Script](/docs/deployments/custom-scripts/run-a-script-step) step. The difference is that the result is committed back to Git rather than deployed to a target. + +:::div{.info} +The Commit to Git step is currently in Early Access. The available options may change as we refine the step based on your feedback. +::: + +## Caveats + +Before you configure the step, note the following limitations on the destination repository: + +- The destination repository must use a credential from the [Git credential library](/docs/infrastructure/git-credentials). GitHub App connections aren't supported for the destination repository. +- To create or wait for pull requests, the credential must use a username and password. SSH credentials can commit directly to the target branch, but they can't create or wait for pull requests. +- Pull requests can only be created for GitHub, GitLab, and Azure DevOps repositories. + +## Destination Git repository + +:::figure +![The Commit to Git step in the process editor](/docs/img/deployments/git/commit-to-git/commit-to-git-step.png) +::: + +The destination repository is the repository you commit to. Configure it with the following options: + +- **Git credential** select the [Git credential](/docs/infrastructure/git-credentials) for the destination repository. See [Caveats](#caveats) for the credential types you can use. +- **Branch** the branch to commit to. This defaults to `main`. +- **Destination path** the path in the repository where Octopus copies your input files. Leave it blank to use the root of the repository. + +### Commit message + +The commit message has a summary and an optional description. If you leave the description blank, Octopus populates a default for you. If you commit through a pull request, Octopus reuses this message for the pull request. + +:::div{.warning} +If the commit summary or description references a [sensitive variable](/docs/projects/variables/sensitive-variables), the deployment fails. This stops sensitive data leaking to Git through the commit or pull request message. +::: + +### Git commit method + +The Git commit method controls how Octopus applies the change to your target branch: + +- **Direct commit** commits straight to the target branch. +- **Pull request** opens a pull request instead of committing directly. + +If you open pull requests, you can do so for all environments or only a selection. Environments you don't select commit directly to the target branch. See [Caveats](#caveats) for the providers that support pull requests. + +## Input files (optional) + +Input files are the files you want to commit. Each input source comes from either a package or a Git repository. You can't use inline content as an input file. + +For each input source, specify: + +- The package or Git repository to take files from. +- **Input file paths**, one or more glob patterns that select the files to copy. +- **Destination subfolder**, the subfolder, under the destination path, to copy the matched files into. + +:::div{.info} +Octopus copies matched files flat into the destination subfolder, so the directory structure of the source isn't preserved. If you need a nested layout in the destination, add a separate input source for each target subfolder. +::: + +## Script (optional) + +You can run a single script during the step, for example to transform your input files before Octopus commits them. The script can be Bash, PowerShell, C#, or Python, and you can source it inline, from a package, or from a Git repository. + +- For package and Git repository scripts, you can pass parameters and reference other packages as dependencies. Inline scripts don't support parameters. +- The script runs from the standard Calamari working directory, with the cloned destination repository available to it. Octopus exposes the path to the repository through the `Octopus.Calamari.Git.RepositoryPath` variable, which points to the root of the repository so your script can read and modify files before the commit. + +## Step verification + +Step verification controls how Octopus decides the step succeeded. There are 2 options. + +:::figure +![The step verification options in the process editor](/docs/img/deployments/git/commit-to-git/commit-to-git-step-verification.png) +::: + +### Direct commit or pull request created + +Octopus confirms the changes were committed to Git, then completes the step without any further checks. + +### Pull request merged + +Octopus pauses the deployment until all the pull requests created by the step are merged. For environments that commit directly, Octopus doesn't wait. + +Octopus reviews this status once every 60 seconds. While the task is paused, the deployment doesn't count toward your task cap. + +## What happens during deployment + +When you deploy a release with a Commit to Git step, Octopus: + +- Clones the destination repository on the worker. +- Copies the configured input files into their destination subfolders. +- Runs your script, if you configured one. +- Commits the changed files, and either pushes them to the target branch or opens a pull request, based on the commit method for the environment. +- Waits until the pull requests are merged before completing, if step verification is set to pull request merged. + +## Output variables + +The step creates [output variables](/docs/projects/variables/output-variables) you can use in later steps. Each is empty if no pull request was created. + +| Variable name | Content | +| ------------------------------ | ---------------------------------------------------------------- | +| CommitToGit.PullRequest.Title | The title of the pull request created by the step. | +| CommitToGit.PullRequest.Number | The identifier of the pull request in your Git repository. | +| CommitToGit.PullRequest.Url | The URL of the pull request created by the step. | +| CommitToGit.PullRequest.RepositoryUrl | The URL of the repository the pull request was created in. | + +## Learn more + +- [Git credentials](/docs/infrastructure/git-credentials) +- [Output variables](/docs/projects/variables/output-variables) +- [Sensitive variables](/docs/projects/variables/sensitive-variables) diff --git a/src/pages/docs/deployments/git/index.md b/src/pages/docs/deployments/git/index.md new file mode 100644 index 0000000000..a49f2f7b81 --- /dev/null +++ b/src/pages/docs/deployments/git/index.md @@ -0,0 +1,14 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-06-03 +modDate: 2026-06-03 +title: Git +description: Built-in steps for committing packages and files to a Git repository as part of your deployment process. +icon: fa-brands fa-git-alt +navOrder: 90 +hideInThisSectionHeader: true +--- + +Octopus includes built-in steps that commit packages and files to a Git repository as part of your deployment process. These steps let you write deployment artifacts back to Git, so you can drive GitOps workflows and keep a versioned history of what you deploy. + +- [Commit to Git](/docs/deployments/git/commit-to-git) copies files from packages and other Git repositories into a target repository, optionally transforms them with a script, and commits the result directly or through a pull request. From 0fa32d17457e5e5d2f08191424cbc2353a9f8ba4 Mon Sep 17 00:00:00 2001 From: Trent Mohay Date: Wed, 3 Jun 2026 16:01:54 +1000 Subject: [PATCH 2/2] docs(deployments): align output variables table to fix markdownlint MD060 Co-Authored-By: Claude Opus 4.8 (1M context) --- src/pages/docs/deployments/git/commit-to-git.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/pages/docs/deployments/git/commit-to-git.md b/src/pages/docs/deployments/git/commit-to-git.md index 6cde6df9d6..06ce7d20db 100644 --- a/src/pages/docs/deployments/git/commit-to-git.md +++ b/src/pages/docs/deployments/git/commit-to-git.md @@ -105,11 +105,11 @@ When you deploy a release with a Commit to Git step, Octopus: The step creates [output variables](/docs/projects/variables/output-variables) you can use in later steps. Each is empty if no pull request was created. -| Variable name | Content | -| ------------------------------ | ---------------------------------------------------------------- | -| CommitToGit.PullRequest.Title | The title of the pull request created by the step. | -| CommitToGit.PullRequest.Number | The identifier of the pull request in your Git repository. | -| CommitToGit.PullRequest.Url | The URL of the pull request created by the step. | +| Variable name | Content | +| ------------------------------------- | ---------------------------------------------------------- | +| CommitToGit.PullRequest.Title | The title of the pull request created by the step. | +| CommitToGit.PullRequest.Number | The identifier of the pull request in your Git repository. | +| CommitToGit.PullRequest.Url | The URL of the pull request created by the step. | | CommitToGit.PullRequest.RepositoryUrl | The URL of the repository the pull request was created in. | ## Learn more