Improve docs for custom fields on releases

src/pages/docs/projects/variables/system-variables.md

@@ -45,6 +45,13 @@ The date and time at which the release was created.
 
 Example: *Tuesday 10th September 1:23 PM*
 
+`Octopus.Release.CustomFields[_name_]`
+
+The value of a custom field set on a release.
+
+Example: *4587* for a custom field `Pull Request Number`
+Example: *TST-123* for a custom field `Jira Ticket Number`
+
 ### Release package build information {#release-package-build-information}
 
 `Octopus.Release.Package`

src/pages/docs/releases/channels/index.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2025-02-18
+modDate: 2025-09-23
 title: Channels
 icon: fa-solid fa-arrows-split-up-and-left
 description: Channels allow you to dynamically change the deployment logic and lifecycle of a project based on the version being deployed.
@@ -153,6 +153,22 @@ Some examples:
 ![Advanced patterns example](/docs/img/releases/channels/images/project-repository.png)
 :::
 
+## Custom fields {#custom-fields}
+
+Channels allow you to define which custom fields are required when creating a release within the channel, ensuring you can use them within scripts and steps in the deployment process. A maximum of 10 custom fields can be defined on a channel.
+
+:::div{.hint}
+Support for custom fields in releases is rolling out to Octopus Cloud in Early Access Preview.
+:::
+
+1. When viewing a channel, click **Add Custom Field** in the Custom Fields section.
+2. Enter a name and description for the field.
+3. Click **Save**.
+
+:::figure
+![Screenshot of editing custom fields for a channel showing a custom field for a Pull Request Number](/docs/img/releases/channels/images/channel-custom-fields.png)
+:::
+
 ## Using channels {#using-channels}
 
 Once a project has more than one channel, there a number of places they may be used.

src/pages/docs/releases/creating-a-release.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2024-04-29
-modDate: 2025-09-03
+modDate: 2025-09-23
 title: Creating a release
 description: Learn how to create a release in Octopus Deploy  
 navOrder: 2
@@ -121,17 +121,28 @@ Releases can have custom fields added to them when being created. Custom fields
 - During deployments within scripts and other steps.
 
 :::div{.hint}
-Support for custom fields on releases is rolling out Octopus Cloud in Early Access Preview as part of the Ephemeral Environments feature.
+Support for custom fields on releases is rolling out to Octopus Cloud in Early Access Preview.
 :::
 
-The following restrictions apply to custom fields on releases:
+:::div{.hint}
+Support for custom fields on releases is available from v2.19.0 of the Octopus CLI.
+:::
 
-- A maximum of 10 custom fields can be added to each release.
-- The maximum length of the key and value of each custom field is 150 characters.
+### Required custom fields
+
+Channels can define which custom fields are required when creating a release within the channel. The Octopus Web Portal will prompt you to provide the value for any required custom fields when creating a release. Learn more about [configuring custom fields in channels](/docs/releases/channels).
+
+:::figure
+![Screenshot of Octopus release page showing entering the value of a custom field for a Pull Request Number](/docs/img/releases/images/create-release-custom-fields.png)
+:::
 
-### Limitations
+### Using custom fields in scripts and steps
 
-The following limitations apply to custom fields during the Early Access Preview:
+Custom fields can be used within scripts and steps with the variable `#{Octopus.Release.CustomFields[_name_]}`.
 
-- Specifying specific custom fields as required on a release is not supported.
-- Support for providing custom fields is not yet available in the Octopus CLI.
+### Restrictions
+
+The following restrictions apply to custom fields on releases:
+
+- A maximum of 10 custom fields can be added to each release.
+- The maximum length of the key and value of each custom field is 150 characters.