Skip to content

Document ephemeral environment actions #2997

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
caitlynstocker wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Document ephemeral environment actions #2997

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6874e55
Document ephemeral environment actions
caitlynstocker Dec 22, 2025
0e2e883
Additional linting fixes
caitlynstocker Dec 22, 2025
0a5df6c
Small fixes from copilot
caitlynstocker Dec 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 28 additions & 27 deletions src/pages/docs/packaging-applications/build-servers/github-actions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,14 @@ navOrder: 55

import BuildInformationInReleaseNotesWithArc from 'src/shared-content/build-information/using-build-information-in-release-notes-with-arc.include.md'

Use [GitHub Actions](https://docs.github.com/en/actions/about-github-actions/understanding-github-actions) to orchestrate Octopus from your CI pipeline for a seamless CI/CD workflow.
Use [GitHub Actions](https://docs.github.com/en/actions/about-github-actions/understanding-github-actions) to orchestrate Octopus from your CI pipeline for a seamless CI/CD workflow.

Integrating GitHub Actions with Octopus Deploy allows you to trigger events in Octopus (like creating a Release) based on events in GitHub (like pushing to main) for an effortless transition from CI to CD.

## Octopus Deploy Actions

Octopus Deploy provides GitHub Actions which enable you to:

- [Log into Octopus Deploy](https://github.com/marketplace/actions/login-to-octopus-deploy)
- [Install Octopus CLI](https://github.com/marketplace/actions/install-octopus-cli)
- [Create a Release](https://github.com/marketplace/actions/create-release-in-octopus-deploy)
Expand All @@ -27,13 +28,16 @@ Octopus Deploy provides GitHub Actions which enable you to:
- [Create a Zip Package](https://github.com/marketplace/actions/create-zip-package-for-octopus-deploy)
- [Create a NuGet Package](https://github.com/marketplace/actions/create-nuget-package-for-octopus-deploy)
- [Push Packages to Octopus Deploy](https://github.com/marketplace/actions/push-package-to-octopus-deploy)
- [Create an Ephemeral Environment](https://github.com/marketplace/actions/create-an-ephemeral-environment-in-octopus-deploy)
- [Deprovision an Ephemeral Environment](https://github.com/marketplace/actions/deprovision-an-ephemeral-environment-in-octopus-deploy)
Copy link
Contributor Author

@caitlynstocker caitlynstocker Dec 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These two lines are the only actual changes!! The rest is linting.

- [Wait for/ watch an Execution Task](https://github.com/marketplace/actions/wait-watch-an-execution-task-in-octopus-deploy)

## Getting started

Octopus Deploy GitHub Actions can be easily incorporated into your own GitHub Action workflows by including them as steps in your workflow YAML. Here is a simple workflow YAML to get you started.

### Example workflow - Create and deploy a release

```yaml
# .github/workflows/hello-octopus-deploy.yml
name: Hello Octopus Deploy
Expand Down Expand Up @@ -94,40 +98,39 @@ jobs:

### ✍️ Environment variables

| Name | Description |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OCTOPUS_SPACE` | The Name of the Space where this command will be executed. |
| `OCTOPUS_URL` | The base URL hosting Octopus Deploy (i.e. `https://octopus.example.app`). It is strongly recommended that this value retrieved from a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions). |
| `OCTOPUS_API_KEY` | The API key used to access Octopus Deploy. It is strongly recommended that this value retrieved from a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions). |

| Name | Description |
| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `OCTOPUS_SPACE` | The Name of the Space where this command will be executed. |
| `OCTOPUS_URL` | The base URL hosting Octopus Deploy (i.e. `https://octopus.example.app`). It is strongly recommended that this value be retrieved from a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions). |
| `OCTOPUS_API_KEY` | The API key used to access Octopus Deploy. It is strongly recommended that this value be retrieved from a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions). |

### 📥 Inputs

| Name | Description |
| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project` | The name of the Project associated with this Release. |
| `release_number` | The number for the new Release. If omitted, Octopus Deploy will generate a Release number. |
| `environments` | A list of Environments in Octopus Deploy in which to run (i.e. Dev, Test, Prod). Add each environment on a new line. |
| `variables` | A list of Variables to use in the Deployment in `key: value` format. Add each variable on a new line. |
| `git_ref` | The Git branch from which to source the project code. Required for Projects using version control in Octopus. The example above sources this value from the workflow's [contextual information.](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context) |
| `git_commit` | The Git commit from which to source the project code. Required for Projects using version control in Octopus. The example above sources this value from the workflow's [contextual information.](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context) |
| `server` | The base URL hosting Octopus Deploy (i.e. `https://octopus.example.app`). It is strongly recommended that this value retrieved from a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions). |
| `service_account_id` | The id of the OIDC service account you wish to login as. Service accounts can be viewed and created on the Octopus app under 'Users' on the configuration menu. |

| Name | Description |
| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `project` | The name of the Project associated with this Release. |
| `release_number` | The number for the new Release. If omitted, Octopus Deploy will generate a Release number. |
| `environments` | A list of Environments in Octopus Deploy in which to run (i.e. Dev, Test, Prod). Add each environment on a new line. |
| `variables` | A list of Variables to use in the Deployment in `key: value` format. Add each variable on a new line. |
| `git_ref` | The Git branch from which to source the project code. Required for Projects using version control in Octopus. The example above sources this value from the workflow's [contextual information.](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context) |
| `git_commit` | The Git commit from which to source the project code. Required for Projects using version control in Octopus. The example above sources this value from the workflow's [contextual information.](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context) |
| `server` | The base URL hosting Octopus Deploy (i.e. `https://octopus.example.app`). It is strongly recommended that this value be retrieved from a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions). |
| `service_account_id` | The id of the OIDC service account you wish to login as. Service accounts can be viewed and created on the Octopus app under 'Users' on the configuration menu. |

## Handling packages

To help you package your files for deployment, Octopus Deploy provides actions to [Create a Zip Package](https://github.com/marketplace/actions/create-zip-package-for-octopus-deploy) or [Create a NuGet Package](https://github.com/marketplace/actions/create-nuget-package-for-octopus-deploy).
To help you package your files for deployment, Octopus Deploy provides actions to [Create a Zip Package](https://github.com/marketplace/actions/create-zip-package-for-octopus-deploy) or [Create a NuGet Package](https://github.com/marketplace/actions/create-nuget-package-for-octopus-deploy).

Alternatively, you can [Install the Octopus CLI](https://github.com/marketplace/actions/install-octopus-cli) and create packages using the [pack command](https://octopus.com/docs/octopus-rest-api/octopus-cli/pack).
Alternatively, you can [Install the Octopus CLI](https://github.com/marketplace/actions/install-octopus-cli) and create packages using the [pack command](https://octopus.com/docs/octopus-rest-api/octopus-cli/pack).

Once your packages are created, simply push them to the Octopus Server built-in repository using our [Push Packages](https://github.com/marketplace/actions/push-package-to-octopus-deploy) Octopus Action.
Once your packages are created, simply push them to the Octopus Server built-in repository using our [Push Packages](https://github.com/marketplace/actions/push-package-to-octopus-deploy) Octopus Action.

You can confirm that your packages have been successfully added by checking for them in your Space under 'Packages'.

Here is a simple example of how to create, push and use a Zip package in a Release.

### Example workflow - Working with packages

```yaml
# .github/workflows/hello-octopus-packages.yml
name: Hello Octopus Packages
Expand Down Expand Up @@ -186,7 +189,7 @@ jobs:
HelloPackage:1.0.0
```

### 📥 Additional inputs
<h3 id="additional-inputs-1">📥 Additional inputs</h3>

| Name | Description |
| :-------------------- | :----------------------------------------------------------------------------------------------------------------|
Expand Down Expand Up @@ -270,7 +273,7 @@ jobs:
HelloPackage:1.0.0
```

### 📥 Additional inputs
<h3 id="additional-inputs-2">📥 Additional inputs</h3>

| Name | Description |
| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------|
Expand All @@ -286,18 +289,16 @@ jobs:

## Runners

Octopus Deploy GitHub Actions can be run on every available type of [runner](https://docs.github.com/en/actions/about-github-actions/understanding-github-actions#runners) (Ubuntu Linux, Microsoft Windows, macOS, and Self-Hosted).
Octopus Deploy GitHub Actions can be run on every available type of [runner](https://docs.github.com/en/actions/about-github-actions/understanding-github-actions#runners) (Ubuntu Linux, Microsoft Windows, macOS, and Self-Hosted).

If your Octopus Server is not accessible over the internet, you can connect to it using a [Self-Hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners).


## Sequencing tasks

It can be useful to run multiple Octopus Deploy GitHub Actions in sequence as part of a workflow. To do this, simply include each Octopus Action as a step within a single job.
It can be useful to run multiple Octopus Deploy GitHub Actions in sequence as part of a workflow. To do this, simply include each Octopus Action as a step within a single job.

If you need to run sequential actions in separate jobs, you can also configure your jobs to run sequentially by [defining prerequisite jobs](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-jobs-in-a-workflow#defining-prerequisite-jobs).


## Previous versions

Since the release of v3, Octopus Deploy GitHub Actions no longer need the [Install Octopus CLI](https://github.com/marketplace/actions/install-octopus-cli) package to be installed before running. [Each Octopus Action](#octopus-deploy-actions) introduced before v3 provides a guide to migrating to v3.