Docs for channels and lifecycles in project templates by N-lson · Pull Request #3464 · OctopusDeploy/docs

N-lson · 2026-09-16T03:47:49Z

Adding documentation around project template lifecycles and channels.

closes SEA-2
closes SEA-5
closes SEA-12

team-marketing-branch-protections · 2026-09-16T04:03:53Z

Pull request environment is available at https://stoctodocspr3464.z22.web.core.windows.net/.

You can view the ephemeral environment status in Octopus Deploy.

This environment will be automatically deprovisioned when the pull request is closed, or after 7 days of inactivity.

IsaacCalligeros95

A couple of comments/thoughts, nothing major and don't feel like they need to be addressed. Corey & Ryan will probably have a better perspective on the docs but figured I'd have a quick read

IsaacCalligeros95 · 2026-09-22T00:43:17Z

 Without a shared definition of breaking vs. non-breaking, teams will interpret these differently. A starting point for a versioning policy:

- **Major**: The change fundamentally alters how the template works. Parameters have been added or removed. Consumers need to review and test the update before accepting it.
+- **Major**: The change fundamentally alters how the template works. Parameters have been added or removed, or a channel has been renamed or deleted. Consumers need to review and test the update before accepting it.


Nit: Is it worth mentioning lifecycles here as well or do we only do this for channels?

This doesn't appear to happen for lifecycles, and I'd hazard a guess because we don't reference lifecycles outside of the channel. You don't scope to a lifecycle so deleting it/renaming it only has to be updated in the channel reference.

IsaacCalligeros95 · 2026-09-22T00:51:11Z

+- Existing releases that reference the channel stop working until someone re-maps them to another channel.
+- Existing triggers that reference the channel stop working until someone re-maps them to another channel.
+
+When making such changes publish a major version, so consumers can review and apply the change deliberately.


Because this is enforced would something along the lines of this work?

Suggested change

When making such changes publish a major version, so consumers can review and apply the change deliberately.

Major versioning is enforced for these changes so consumers can review and adopt the updates deliberately.

IsaacCalligeros95 · 2026-09-22T00:52:14Z

+
+In a project template, channels reference lifecycles that reside within the project template itself.
+
+Unlike a regular project, a project template lets you delete a channel or change its filename even when projects using the template have releases or triggers that reference it. Doing so has consequences for every project using the template:


Probably not worth adding, I think this would be clear to most users but it might clarify things

Suggested change

Unlike a regular project, a project template lets you delete a channel or change its filename even when projects using the template have releases or triggers that reference it. Doing so has consequences for every project using the template:

Unlike a regular project, a project template lets you delete a channel or change its filename even when projects using the template have releases or triggers that reference it. Doing so has consequences for every project using the template at publish time:

Building on your suggestion Isaac:

Suggested change

Unlike a regular project, a project template lets you delete a channel or change its filename even when projects using the template have releases or triggers that reference it. Doing so has consequences for every project using the template:

Unlike a regular Project, a Project Template allows you to delete a Channel or change it's filename in OCL, even when Projects using the template have Releases or Triggers that reference it. Publishing a new version of the Project Template with these changes will have consequences for Projects that accept the new version:

IsaacCalligeros95 · 2026-09-22T00:53:07Z


+## Channels
+
+[Channels](/docs/releases/channels) in project templates function the same as they do in projects. You can define channels based on the intended release strategies for projects that use this template. Every project template comes with a default channel.


Is it worth calling out that tenants are passed through via parameters similar to how environments are passed through to templated lifecycles?

Agreed that'd be good to call out as it's one of the differences between Platform Hub and Projects.

corey-underdown · 2026-09-22T05:11:38Z

+[Channels](/docs/releases/channels) in project templates function the same as they do in projects. You can define channels based on the intended release strategies for projects that use this template. Every project template comes with a default channel.
+
+:::div{.warning}
+Ephemeral environment channels aren't yet supported in project templates.


Project Templates should be capitalised as they're a noun. The same applies to all the usages of Channels/Lifecycles/Projects etc.

I've checked through our docs, and we're really inconsistent with this so it's probably okay to just leave them as is.

I checked our writing guide skill, and it defines:

"As a general rule, capitalize words and terms that are proper nouns or would normally be capitalized. If you're uncertain, default to not capitalizing terms."

The fact that we capitalize Platform Hub says we should extend that capitalization to all Octopus concepts, but like I said we're fairly inconsistent with this, leaning more towards not using them. So for now let's leave it, and we'll reflect on it across all our Platform Hub docs at once.

I find it very hard to know when to capitalise and when not too. According to the writing guide there is a difference between talking about the feature Project Templates (should be capitalised) and a group of project templates (lowercase) or a single project template (lowercase).

The sentence above could be either IMO. 🤷‍♀️

Like you said - I'm going to leave it for now

corey-underdown

Looks good, covers all the things on my mind. Few wording suggestions.

Can ignore my comments around capitalization of proper nouns. We're so inconsistent and not capitalizing matches better to existing docs.

corey-underdown · 2026-09-22T05:18:04Z

+
+In a project template, channels reference lifecycles that reside within the project template itself.
+
+Unlike a regular project, a project template lets you delete a channel or change its filename even when projects using the template have releases or triggers that reference it. Doing so has consequences for every project using the template:


Building on your suggestion Isaac:

Suggested change

Unlike a regular project, a project template lets you delete a channel or change its filename even when projects using the template have releases or triggers that reference it. Doing so has consequences for every project using the template:

Unlike a regular Project, a Project Template allows you to delete a Channel or change it's filename in OCL, even when Projects using the template have Releases or Triggers that reference it. Publishing a new version of the Project Template with these changes will have consequences for Projects that accept the new version:

corey-underdown · 2026-09-22T05:19:18Z

+- Existing releases that reference the channel stop working until someone re-maps them to another channel.
+- Existing triggers that reference the channel stop working until someone re-maps them to another channel.
+
+When making such changes publish a major version, so consumers can review and apply the change deliberately.


corey-underdown · 2026-09-22T05:28:33Z

+[Channels](/docs/releases/channels) in project templates function the same as they do in projects. You can define channels based on the intended release strategies for projects that use this template. Every project template comes with a default channel.
+
+:::div{.warning}
+Ephemeral environment channels aren't yet supported in project templates.


I've checked through our docs, and we're really inconsistent with this so it's probably okay to just leave them as is.

I checked our writing guide skill, and it defines:

"As a general rule, capitalize words and terms that are proper nouns or would normally be capitalized. If you're uncertain, default to not capitalizing terms."

The fact that we capitalize Platform Hub says we should extend that capitalization to all Octopus concepts, but like I said we're fairly inconsistent with this, leaning more towards not using them. So for now let's leave it, and we'll reflect on it across all our Platform Hub docs at once.

N-lson force-pushed the nelson/project-template-channels branch 2 times, most recently from 566280f to 5dcc747 Compare September 21, 2026 00:46

N-lson marked this pull request as draft September 21, 2026 00:46

clairey259 marked this pull request as ready for review September 21, 2026 07:02

N-lson and others added 2 commits September 21, 2026 17:05

channels and lifecycles wip

ccef49e

wip

4c8cbe3

clairey259 force-pushed the nelson/project-template-channels branch from 8514769 to 4c8cbe3 Compare September 21, 2026 07:05

clean up

52eb1e1

IsaacCalligeros95 reviewed Sep 22, 2026

View reviewed changes

corey-underdown reviewed Sep 22, 2026

View reviewed changes

corey-underdown approved these changes Sep 22, 2026

View reviewed changes

clairey259 added 2 commits September 22, 2026 16:58

pr feedback

61bd8bf

add version info

d673df2

clairey259 force-pushed the nelson/project-template-channels branch from 526a029 to d673df2 Compare September 23, 2026 06:35

clairey259 merged commit dda6317 into main Sep 23, 2026
7 checks passed

clairey259 deleted the nelson/project-template-channels branch September 23, 2026 06:54

	When making such changes publish a major version, so consumers can review and apply the change deliberately.
	Major versioning is enforced for these changes so consumers can review and adopt the updates deliberately.


		In a project template, channels reference lifecycles that reside within the project template itself.

		Unlike a regular project, a project template lets you delete a channel or change its filename even when projects using the template have releases or triggers that reference it. Doing so has consequences for every project using the template:


		## Channels

		[Channels](/docs/releases/channels) in project templates function the same as they do in projects. You can define channels based on the intended release strategies for projects that use this template. Every project template comes with a default channel.

Conversation

N-lson commented Sep 16, 2026 • edited by clairey259 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

team-marketing-branch-protections commented Sep 16, 2026

Uh oh!

IsaacCalligeros95 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

corey-underdown Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

corey-underdown left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

N-lson commented Sep 16, 2026 •

edited by clairey259

Loading

corey-underdown Sep 22, 2026 •

edited

Loading