Deployment target triggers

Deployment target triggers (also known as auto-deploy) let you to define an unattended behavior for your projects that will cause an automatic deployment of a release into an environment. This means, you can configure new deployment targets to be just like their counterparts.

Deployment target triggers can help you:

• Elastically scale a farm of servers.
• Automatically keep your deployment targets up to date without needing to perform manual deployments.
• Deploy to transient deployment targets (targets that are disconnected from time to time).
• Implement immutable infrastructure environments (sometimes called “Phoenix Environments”).
• Remove deployment targets that have gone offline. For instance, disable a machine in Octopus and have a deployment process that removes disabled machines from your load balancer.

On the surface deployment target triggers appear to be simple, however they can grow complex very quickly and we recommend reading our Elastic and Transient Environments guide before getting started with your own implementation.

Defining deployment target triggers

Deployment target triggers can be triggered by any machine-related event. A scheduled task runs in Octopus every 30 seconds looking for new events to determine whether any automatic deployment triggers need to fire. Each trigger is inspected to see if the recent stream of events should cause the trigger to fire, and if so, the appropriate deployments will be queued and run for the deployment target(s) that caused the trigger to fire.

Events have been placed into the following pre-defined groups:

As you define your deployment target triggers, you can select the pre-defined event groups or individual events:

• Machine cleanup failed
• Machine created
• Machine deployment-related property modified
• Machine disabled
• Machine enabled
• Machine found healthy
• Machine found to be unavailable
• Machine found to be unhealthy
• Machine found to have warnings

You can restrict deployments target triggers further by specifying the following:

• The environment(s) the trigger applies to.
• The target tags the trigger applies to.
• The environment and target tags the trigger applies to.

Add a deployment target trigger

1. From a project, select Triggers, then Add Trigger ➜ Deployment target.
2. Give the trigger a name.
3. Specify the event group or individual events that will trigger the releases.
4. If you want to limit the trigger to specific environments, select those environments.
5. If you want to limit the trigger to specific target tags, select those target tags.
6. Specify whether or not to re-deploy to deployment targets even if they are already up-to date with the current deployment.
7. Save the trigger.

With the trigger save, Octopus will run a scheduled task every 30 seconds looking for events that machine the deployment trigger.

Unattended release behavior

Deployment target triggers let you configure unattended deployment behavior that configures new deployment targets to be just like their counterparts.

When a deployment target trigger fires, the following rules are applied:

• By default, Octopus will re-run the currently successful deployment for the project/environment/tenant combination. You can override this behavior by configuring an auto deploy override. Note, if multiple identical deployment targets all become available within the same 30 second polling window, they will all be included in the same automatic deployment. This could happen if you scale your web farm up by four nodes, and all four nodes finish provisioning within the same time window. However, this kind of behavior should not be expected or relied on (one or more of the targets might fall outside the 30 second window).
• The steps that were run for the currently successful deployment will be run for the deployment targets that triggered the deployment. This includes manual intervention and guided failure steps. Note, if you skip steps in a manual deployment, they will be skipped in the subsequent automatic deployment. If you need to run a deployment and skip some steps, there are two ways you can reset the skipped steps:
  1. Re-running the entire deployment of the same release again (we generally recommend designing your steps so they can be re-run without negative side-effects).
  2. Configuring an auto deploy override for the same release to the same environment/tenant (this will result in a new deployment being generated without the manually skipped steps).
• If a deployment of a release fails, Octopus will continue deploying the last successful deployment. This ensures auto-deployments will continue, even if a release has been updated and failed.

The order of deployment target triggers

Because projects are considered independent in Octopus, and there is no built-in way to define dependencies between projects or control the order in which projects are deployed.

One workaround for this is to create a project in Octopus with the job of orchestrating the deployment of multiple projects.

In this case you could:

1. Create a project that orchestrates the deployment of multiple projects.
2. Each step in the deployment process of this project could call the Octopus API to deploy the next project in the dependency chain, waiting for a successful deployment before continuing to the next project.
3. Optionally create an deployment target trigger in the orchestrating project to start the whole process.

Specifying a specific release to be deployed

If you need to specify a specific release, either because the release hasn’t been deployed yet, or Octopus is calculating the wrong release for a particular situation, you can configure an auto deploy override to override the default automatic deployment behavior. This is useful for scenarios like immutable infrastructure, deploying to transient targets, and force deployment target triggers to use a specific release for a specific environment/tenant.

Deployment target trigger subscription notifications

If you want to be notified of automatic deployments events, like blockages or failures, you can configure subscriptions to notify you by email or use web hooks to create your own notification channels. You can even use web hooks to code your own recovery behavior based on your specific situation.

Troubleshooting deployment target triggers

There are a number of reasons why automatic deployments may not work the way you expected, some of which we’ve already discussed earlier. Here are some troubleshooting steps you can take to figure out what is going wrong.

Is the dashboard green?

Octopus will attempt to automatically deploy the current releases for the environments that are appropriate for a machine. The current release is the one that was most recently successfully deployed as shown on the project dashboard.

• Octopus will not automatically deploy a release if the deployment for that release was not successful (this can be a failed deployment or even a canceled deployment)

You will need you to complete a successful deployment again before auto-deployments can continue for the given release, or configure an auto deploy override.

Investigate the diagnostic logs

Go to Configuration ➜ Diagnostics ➜ Auto deploy logs. The verbose logs usually contain the reason why a project trigger didn’t take any action. For example:

Auto-deploy: Machine 'Local' does not need to run release '2.6.6' for project 'My Project' and tenant '<none>' because it already exists on the machine or is pending deployment.

Investigate the audit messages

The deployment triggers are all triggered based on events occurring in Octopus, all of which are logged reliably as audit events. Go to Configuration ➜ Audit and filter down to see the events related to your deployments.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Wednesday, August 28, 2024