Project Templates docs by IsaacCalligeros95 · Pull Request #3054 · OctopusDeploy/docs

IsaacCalligeros95 · 2026-03-06T05:54:17Z

Adds Project Templates docs. since there's a significant overlap with Process Templates I've separated out some common pages and re-worked the page heirachy here.

Questions:

Should the consumer & producer docs be together?
Can we just use producer & consumer terminology? We already do in the process templates best practices docs and I find it helpful.
Are we okay with the "Templated Project" terminology? I like it, I'm not the best at naming these sorts of things especially in a customer facing place.
The best practices have a lot of overlap with process templates, I also haven't focused on this much. Is it worth including this as part of our Alpha release? (I think it's better to just delete it)

MAS-2353

Copilot

Pull request overview

Adds/relocates Platform Hub “Templates” documentation, introducing Project Templates docs alongside Process Templates docs, and updates navigation/links to the new structure while preserving legacy URLs via redirects.

Changes:

Add new Templates overview, parameters reference, and shared “Publishing and sharing” page.
Add Project Templates docs (overview, best practices, troubleshooting) and related image assets.
Move Process Templates docs under /docs/platform-hub/templates/... and convert the old /docs/platform-hub/process-templates/... pages into redirects; update Platform Hub landing page links accordingly.

Reviewed changes

Copilot reviewed 18 out of 45 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/pages/docs/platform-hub/templates/publishing-and-sharing.md	New shared doc for saving/publishing/sharing templates
src/pages/docs/platform-hub/templates/project-templates/index.md	New Project Templates overview doc
src/pages/docs/platform-hub/templates/project-templates/best-practices.md	New Project Templates best practices doc
src/pages/docs/platform-hub/templates/project-templates/troubleshooting.md	New Project Templates troubleshooting doc
src/pages/docs/platform-hub/templates/process-templates/index.md	New Process Templates overview doc under Templates section
src/pages/docs/platform-hub/templates/process-templates/best-practices.md	New Process Templates best practices doc under Templates section
src/pages/docs/platform-hub/templates/process-templates/troubleshooting.md	New Process Templates troubleshooting doc under Templates section
src/pages/docs/platform-hub/templates/parameters.md	New shared parameter reference for template types
src/pages/docs/platform-hub/templates/index.md	New Templates landing/overview page
src/pages/docs/platform-hub/process-templates/index.md	Redirect legacy Process Templates overview URL to new location
src/pages/docs/platform-hub/process-templates/best-practices.md	Redirect legacy Process Templates best practices URL to new location
src/pages/docs/platform-hub/process-templates/troubleshooting.md	Redirect legacy Process Templates troubleshooting URL to new location
src/pages/docs/platform-hub/index.md	Update Platform Hub landing page to link to new templates structure and add Project Templates link
public/docs/img/platform-hub/project-templates/project-templates-usage.png.json	Image metadata for new Project Templates usage screenshot
public/docs/img/platform-hub/project-templates/project-templates-process-overview.png.json	Image metadata for new Project Templates process overview screenshot
public/docs/img/platform-hub/project-templates/project-templates-onboarding.png.json	Image metadata for new Project Templates onboarding screenshot
public/docs/img/platform-hub/project-templates/project-templates-list.png.json	Image metadata for new Project Templates list screenshot
public/docs/img/platform-hub/project-templates/project-template-process-editor.png.json	Image metadata for new Project Templates process editor screenshot
public/docs/i/600/platform-hub/project-templates/project-templates-usage.webp	600px responsive image for Project Templates usage screenshot
public/docs/i/600/platform-hub/project-templates/project-templates-process-overview.webp	600px responsive image for Project Templates process overview screenshot
public/docs/i/600/platform-hub/project-templates/project-templates-onboarding.webp	600px responsive image for Project Templates onboarding screenshot
public/docs/i/600/platform-hub/project-templates/project-templates-list.webp	600px responsive image for Project Templates list screenshot
public/docs/i/600/platform-hub/project-templates/project-template-process-editor.webp	600px responsive image for Project Templates process editor screenshot
public/docs/i/1000/platform-hub/project-templates/project-templates-process-overview.webp	1000px responsive image for Project Templates process overview screenshot
public/docs/i/1000/platform-hub/project-templates/project-templates-onboarding.webp	1000px responsive image for Project Templates onboarding screenshot
public/docs/i/1000/platform-hub/project-templates/project-templates-list.webp	1000px responsive image for Project Templates list screenshot

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/pages/docs/platform-hub/templates/parameters.md

src/pages/docs/platform-hub/templates/process-templates/index.md

src/pages/docs/platform-hub/templates/project-templates/index.md

src/pages/docs/platform-hub/templates/project-templates/troubleshooting.md

src/pages/docs/platform-hub/templates/parameters.md

steve-fenton-octopus · 2026-03-09T08:01:38Z

I had a quick look at the test failure and when I pull the branch I can't see the image:

Maybe you have it locally?

/public/docs/img/platform-hub/project-templates/project-templates-parameters.png

IsaacCalligeros95 · 2026-03-09T21:44:49Z

I had a quick look at the test failure and when I pull the branch I can't see the image:

Maybe you have it locally?
/public/docs/img/platform-hub/project-templates/project-templates-parameters.png

Hey Steve, thanks for looking I managed to name it .../project-templates-parameters.png.png 🤦 should be right now. This is still a WIP, I meant to leave it as a draft sorry if the open setting triggered notifications/checks for you

N-lson

Reviewed most of the files, will have a look at the rest in a bit

public/docs/i/2000/platform-hub/project-templates/project-template-selection.webp

src/pages/docs/platform-hub/templates/process-templates/best-practices.md

src/pages/docs/platform-hub/templates/project-templates/best-practices.md

src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md

src/pages/docs/platform-hub/templates/parameters.md

N-lson · 2026-03-16T02:49:47Z

src/pages/docs/platform-hub/templates/parameters.md

+- Username Password Account
+- Worker Pool
+- Package
+- A previous step name


Project parameter missing?

Always was, weird though I added it and then somehow lost it pulling the parameters page out into a shared one...

N-lson

LGTM

src/pages/docs/platform-hub/templates/publishing-and-sharing.md

src/pages/docs/platform-hub/index.md

IsaacCalligeros95 · 2026-03-18T22:58:39Z

@steve-fenton-octopus We're waiting a couple of days until we can enable this feature toggle for a majority of cloud customers and include a version/link for self hosted testing before merging this one. I haven't done a large docs PR in sometime, is this something your team would want to review before we merge? I'm assuming not because there's no branch protections, just wanted to check first though.

octo-ryanhall · 2026-03-19T04:19:23Z

src/pages/docs/platform-hub/templates/project-templates/index.md

+
+## Deployment process
+
+The deployment process defines the steps Octopus orchestrates when deploying a project created from this template. Each project template has a single deployment process, and you can use Octopus's built-in steps, Step Templates, Community Step Templates, and Process Templates to define it.


Suggested change

The deployment process defines the steps Octopus orchestrates when deploying a project created from this template. Each project template has a single deployment process, and you can use Octopus's built-in steps, Step Templates, Community Step Templates, and Process Templates to define it.

The deployment process defines the steps Octopus orchestrates when deploying a project created from this template. Each project template has a single deployment process, and you can use Octopus's built-in steps, step templates, community step templates, and process templates to define it.

Adding this here as I think we may not be following the Octopus grammar rules for proper & common nouns. The way I interpret the style guide is that step templates, community step templates, and process templates are all collections of things and therefore should be lowercase.

This is only one example so I encourage you to self-edit one last time to make sure.

octo-ryanhall · 2026-03-19T04:22:32Z

src/pages/docs/platform-hub/templates/project-templates/index.md

+
+## Parameters
+
+Parameters let you define the inputs a project must supply when it's created from the template. They're the mechanism for making a template flexible. Rather than hardcoding values that differ between teams or spaces, you expose them as parameters.


Should this read Parameters let you define the inputs a user must supply when they create a project from a template.

My reasoning is projects don't provide inputs, users do.

Yep that reads much better, I was trying to make it clear that the values are provided within the project but the phrasing was off.

octo-ryanhall · 2026-03-19T04:24:38Z

src/pages/docs/platform-hub/templates/project-templates/index.md

+
+Variables in a project template work the same way as project variables in a standard Octopus project. Any variable you define is available to the deployment and can be selected in steps.
+
+Unlike parameters, projects can't override the variables set in a template. Use this for values that must be the same across every project, like accounts or credentials. If you want projects to supply their own value for something, expose it as a parameter instead.


This is another one where it might be easier to grasp the concept if we describe the action that the user is taking and the expected behaviour.

octo-ryanhall · 2026-03-19T04:26:48Z

src/pages/docs/platform-hub/templates/project-templates/index.md

+
+## Git repository structure
+
+Octopus stores each project template as a folder in the Platform Hub Git repository. The folder name is a slug derived from the template name. Each folder contains four OCL files:


For OCL, should we add a link to the Configuration as Code docs?

MissedTheMark

Over-all, really good work! Couple of comments I'd like to see addressed before we merge this.

src/pages/docs/platform-hub/templates/project-templates/best-practices.md

MissedTheMark · 2026-03-19T04:19:25Z

src/pages/docs/platform-hub/templates/project-templates/best-practices.md

+
+### Write release notes when publishing a new version
+
+Each published version can include release notes. Describe what changed, whether any parameters were added or removed, and what consumers need to do when updating.


I don't think we actually show release notes to the consumer anywhere? At least not on the 'update to version' part of project settings.

Yeah they aren't shown anywhere, I think it's still good to include as a best practice for when we do display them.

src/pages/docs/platform-hub/templates/project-templates/index.md

src/pages/docs/platform-hub/templates/project-templates/installation-guide.md

src/pages/docs/platform-hub/templates/project-templates/troubleshooting.md

src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md

MissedTheMark · 2026-03-19T04:35:39Z

src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md

+## Future direction
+
+We're still shaping what project templates can do, and there are a few areas we're actively thinking about. If any of these sound useful to you, we'd love to hear about it. [Share your feedback](https://oc.to/feedback).
+
+### Placeholders
+
+Placeholders would let producers give consumers some flexibility to add their own steps to a templated project's deployment process. Rather than a fully fixed process, producers could mark specific points where consumers are permitted to insert their own steps.
+
+### Runbooks and triggers
+
+We're planning to support runbooks and triggers defined in the project template, so templated projects inherit them alongside the deployment process. This would let producers standardize operational runbooks and scheduled triggers across all projects created from the template. Projects would still be able to create and manage their own runbooks and triggers.


I'd run this by Ships, I don't know if she's wanting to talk about these yet. I'd be particularly concerned about the placeholders stuff, given that it's a "we might look at it sometime" kind of thing.

octo-ryanhall · 2026-03-19T05:04:01Z

src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md

+![Configuring template version update preferences](/docs/img/platform-hub/project-templates/templated-project-version-settings.png)
+:::
+
+1. Click **Create Project**. You'll be taken to the **Template values** page.


Suggested change

1. Click **Create Project**. You'll be taken to the **Template values** page.

Click **Create Project**. You'll be taken to the **Template values** page.

octo-ryanhall

@IsaacCalligeros95 I have added a few minor suggestions. Feel free to pick and choose what makes sense.

IsaacCalligeros95 · 2026-03-19T05:12:57Z

@IsaacCalligeros95 I have added a few minor suggestions. Feel free to pick and choose what makes sense.

Thanks Ryan, really appreciate the feedback. Taking a look now

…es-docs

IsaacCalligeros95 added 4 commits March 6, 2026 15:49

Add project template docs

4768a00

Update docs

2c9809b

Update docs

c7607b6

Tidy-up

41163bd

IsaacCalligeros95 requested a review from Copilot March 6, 2026 05:54

Copilot started reviewing on behalf of IsaacCalligeros95 March 6, 2026 05:56 View session

Copilot AI reviewed Mar 6, 2026

View reviewed changes

IsaacCalligeros95 added 2 commits March 6, 2026 17:11

Updates

a4981cd

Fix image name

41ae0c2

Fix image name

fef1cea

IsaacCalligeros95 marked this pull request as draft March 9, 2026 21:44

IsaacCalligeros95 added 13 commits March 10, 2026 10:12

New images, some edits.

c11446b

New images, some edits.

caef834

Rewrites

8584ba8

updates

e9ce85f

tidy-up

121680d

Fixing linting issue

b01a9ca

Tidy-up troubleshooting

bdee29a

best practices updates

8a6f829

Validation message

e3baa95

Include initial cut of project template consumers

fbd2848

Include initial cut of project template consumers

f5ec2bf

Rename to templated projects

326f5bc

Fix linting issues, tidy-up

026a825

IsaacCalligeros95 marked this pull request as ready for review March 16, 2026 02:07

IsaacCalligeros95 added 2 commits March 16, 2026 12:53

Add installation guide

3b7cc12

Edits

29c5c7a

N-lson reviewed Mar 16, 2026

View reviewed changes

Addressing PR feedback

87011f9

N-lson approved these changes Mar 16, 2026

View reviewed changes

Pr feedback tidy up

485c67c

steve-fenton-octopus assigned IsaacCalligeros95 Mar 17, 2026

Include download link

fe692f2

IsaacCalligeros95 force-pushed the isaac/project-templates-docs branch from fda2dbb to fe692f2 Compare March 19, 2026 04:07

octo-ryanhall reviewed Mar 19, 2026

View reviewed changes

MissedTheMark reviewed Mar 19, 2026

View reviewed changes

octo-ryanhall reviewed Mar 19, 2026

View reviewed changes

Addressing Marks PR comments

f2b1ac1

octo-ryanhall reviewed Mar 19, 2026

View reviewed changes

IsaacCalligeros95 added 3 commits March 19, 2026 15:57

Addressing Ryans Pr comments

f664982

Merge remote-tracking branch 'origin/main' into isaac/project-templat…

0968d62

…es-docs

Remove future direction placeholders & runbooks/triggers comments

10c8f58

IsaacCalligeros95 merged commit 3e50ae2 into main Mar 19, 2026
5 checks passed

IsaacCalligeros95 deleted the isaac/project-templates-docs branch March 19, 2026 06:14


		## Deployment process

		The deployment process defines the steps Octopus orchestrates when deploying a project created from this template. Each project template has a single deployment process, and you can use Octopus's built-in steps, Step Templates, Community Step Templates, and Process Templates to define it.


		## Parameters

		Parameters let you define the inputs a project must supply when it's created from the template. They're the mechanism for making a template flexible. Rather than hardcoding values that differ between teams or spaces, you expose them as parameters.


		Variables in a project template work the same way as project variables in a standard Octopus project. Any variable you define is available to the deployment and can be selected in steps.

		Unlike parameters, projects can't override the variables set in a template. Use this for values that must be the same across every project, like accounts or credentials. If you want projects to supply their own value for something, expose it as a parameter instead.


		## Git repository structure

		Octopus stores each project template as a folder in the Platform Hub Git repository. The folder name is a slug derived from the template name. Each folder contains four OCL files:


		### Write release notes when publishing a new version

		Each published version can include release notes. Describe what changed, whether any parameters were added or removed, and what consumers need to do when updating.

	1. Click Create Project. You'll be taken to the Template values page.
	Click Create Project. You'll be taken to the Template values page.

Conversation

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

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

steve-fenton-octopus commented Mar 9, 2026

Uh oh!

IsaacCalligeros95 commented Mar 9, 2026

Uh oh!

N-lson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

N-lson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

IsaacCalligeros95 commented Mar 18, 2026

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!

MissedTheMark left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

octo-ryanhall left a comment

Choose a reason for hiding this comment

Uh oh!

IsaacCalligeros95 commented Mar 19, 2026

Uh oh!

Uh oh!

Reviewers

IsaacCalligeros95 commented Mar 6, 2026 •

edited by N-lson

Loading