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..06ce7d20db --- /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.