Consider using a build server extension
We have extensions/plugins available for the most popular build servers. These extensions will help you create packages, push those packages to the built-in repository, create releases and deploy them to your environments:
Take a look at the end-to-end guide for TFS which covers building and packaging your application, creating releases and deploying to your environments.
Built-in repository only
External package repositories cannot be used to automatically create releases, only the built-in package repository is supported.
If you use the built-in Octopus package repository, you can now select a package, that when uploaded it will automatically create a release.
From the project's trigger tab, under the section called Automatic Release Creation, click Setup, and then select the package that will trigger the release:
As a project can contain multiple packages you need to select the package that will upload LAST in your build and push CI process. If you have multiple packages, make sure you select the package that is always uploaded last.
Cannot use variables for PackageId
You cannot use variables to define the PackageId (either in full or in part). Octopus will only create a release on your behalf when you have selected a specific Package (the PackageId must be a constant value).
When a release is set to be created this way, the audit will tell you that is how the release was created.
If you combine uploading a package with the automatic deployment feature within Lifecycles phases, you can push a package to the internal repository, create a release, and have it automatically deploy.
The release number that is created is guided by the Release Versioning settings under Project ➜ Settings. It will use the rules defined.
Channels were introduced in Octopus 3.2, and at this point you must select the Channel that will be used for any automatically created releases. This means that only one channel for each project can have an automatic release creation trigger enabled at any one time. This can be painful, and here are some points you can consider:
- Use one of the build-server extensions, or octo.exe to create releases instead of using ARC - this will automatically determine the best channel based on the release being created
- Choose the channel that will be used most commonly for automatically creating releases, and create releases manually for the other channels.
- Try creating some releases manually for the selected channel to make sure it works as expected.
Automatically Creating Pre-releases
When you push a package to your trigger step, Octopus will look for the latest available package for all other steps excluding pre-release packages by default - see this thread for background.
One way to work around this behavior is to create a Channel with the appropriate version rules so that "latest available package" will be the pre-release packages you expected. The best way to test this is to practice creating releases manually for that channel - the "latest available package" will work the same way for manual and automatically created releases.
When you are using automatic release creation there are many reasons why a release may not be created successfully. Take some time to consider the following troubleshooting steps:
Inspect the server logs for warnings in Configuration ➜ Diagnostics - Octopus will log the reason why automatic release creation failed as errors or warnings.
Ensure you are pushing the package to the built-in package repository - external package repositories are not supported for automatic release creation.
Ensure you have enabled automatic release creation for the project based on the correct package.
When using Channels ensure you have enabled automatic release creation for the desired Channel.
Ensure you are pushing a new version of the package - Octopus will not create a release where the package has already been used for creating a release.
Ensure you are pushing a package that Octopus will consider as the latest available package - see the conversation about automatically creating pre-releases above.
Ensure the release creation package step DOES NOT use variables for the PackageId - Octopus will only create a release where the package is constant.
When a release has multiple packages, ensure you configure automatic release creation to use the last package that is pushed to the built-in repository - otherwise some of the packages required for the release will be missing.
When using Channels the package must satisfy the version rules for the Channel being used for automatic release creation - try creating some releases manually.
Are you pushing pre-release packages? See the section above on automatically creating pre-releases.
Ensure the account pushing the package has the required permissions for each of the Projects and Environments that will be involved in creating (and potentially deploying) the release. Consider which of the following permissions may be required depending on your circumstances: