From c970f07caa0cf46d6cbe9eb08c72d5bf9e41daf0 Mon Sep 17 00:00:00 2001 From: danciaclara Date: Thu, 4 Jun 2026 14:46:39 +0530 Subject: [PATCH 1/3] Send webhook in Automations --- docs/automations/custom-automations.md | 108 +++++++++++++++++++------ 1 file changed, 83 insertions(+), 25 deletions(-) diff --git a/docs/automations/custom-automations.md b/docs/automations/custom-automations.md index b42bfb6..1ee887f 100644 --- a/docs/automations/custom-automations.md +++ b/docs/automations/custom-automations.md @@ -27,8 +27,8 @@ Project automations apply to work items within a single project. 2. In the **Custom automations** section, click **Create automation**. 3. Give your automation a descriptive name and an optional description, then save. 4. Click **Add trigger** and choose the event that should start the automation. -5. Optionally click **Add condition** to narrow when the automation runs. You can add multiple conditions — the automation only fires when all conditions are met. -6. Click **Add action** to define what happens. Choose from **Add comment**, **Change property**, or **Run Script**. You can add multiple actions — they execute in sequence. +5. Optionally click **Add condition** to narrow when the automation runs. You can add multiple conditions - the automation only fires when all conditions are met. +6. Click **Add action** to define what happens. Choose from **Add comment**, **Change property**, or **Run Script**. You can add multiple actions - they execute in sequence. 7. Click **Confirm**. 8. Click **Enable** when you're ready for it to go live. @@ -44,7 +44,7 @@ Workspace automations can span your entire workspace or a specific set of projec 1. Go to **Workspace Settings → Automations**. 2. Click **Create automation**. -3. Choose which projects the automation should apply to — all projects in the workspace, or a specific subset. +3. Choose which projects the automation should apply to - all projects in the workspace, or a specific subset. 4. Follow the same steps as a project automation: name → trigger → conditions → actions. 5. Enable when ready. @@ -72,15 +72,16 @@ Conditions filter which work items an automation acts on. Without them, the auto 4. Choose an operator (is, in, contains, etc.) and set the value. 5. Add more conditions as needed. -Multiple conditions use **AND** logic by default — all of them must match. You can also create **OR** groups where only one condition in the group needs to match. +Multiple conditions use **AND** logic by default - all of them must match. You can also create **OR** groups where only one condition in the group needs to match. ## Add actions 1. Open the automation and go to the **Action** tab. 2. Click **Add action** and choose a type: - - **Change property** — update a field on the work item - - **Add comment** — post a comment on the work item - - **Run script** — execute a saved script via the Runner + - **Change property** - update a field on the work item + - **Add comment** - post a comment on the work item + - **Run script** - execute a saved script via the Runner + - **Send webhook** - POST a payload to an external URL when the automation fires 3. Configure the action details (see [Actions](#actions) for parameters). 4. Add more actions if needed. They run in the order listed. @@ -91,7 +92,7 @@ Multiple conditions use **AND** logic by default — all of them must match. You - **Enable**: open the automation and click **Enable**. The automation must have at least one trigger and one action. - **Disable**: open the automation and click **Disable** or toggle the status off. -You can't delete an enabled automation — disable it first. +You can't delete an enabled automation - disable it first. ### Check automation run history @@ -168,7 +169,7 @@ Updates a field on the work item. Posts a comment on the work item. You write the comment text in a rich text editor. The comment is always internal and appears as coming from Automation Bot in the activity log. -You can include dynamic values in the comment using template variables — for example, inserting the current priority or state name into the comment text. +You can include dynamic values in the comment using template variables - for example, inserting the current priority or state name into the comment text. **Example:** Say you have an automation that triggers when a work item's state changes. You want to leave a note with context each time that happens. Your comment template might look like: @@ -176,6 +177,63 @@ You can include dynamic values in the comment using template variables — for e This item has been moved to a new state. Current priority: {{priority}}. Please check if the due date needs updating. ``` +#### Send webhook + +Posts an HTTP payload to a URL you specify whenever the automation fires. Use this to push automation events into external systems - trigger a deployment, open a ticket in another tool, post to a custom service, or sync data outside of Plane. + +This is different from workspace webhooks, which fire on any matching event across your workspace. A Send webhook action fires only when this specific automation runs - you control the trigger, conditions, and timing. + +**Configuration** + +| Field | Required | Notes | +|---|---|---| +| URL | Yes | Must be a publicly reachable `http://` or `https://` address. Local and private network addresses are not accepted. | +| Secret key | Auto-generated | Generated when you save the action. Shown once in plain text - copy it before leaving. After that it appears masked as `plane_wh_••••XXXX`. | +| Custom headers | No | Up to 20 headers. Mark a header as secret to store its value encrypted - the value won't be returned in subsequent reads. | + +**The secret key** + +Plane generates a secret key when you first save the Send webhook action. It is shown in plain text once - copy and store it before navigating away. After that, it is masked and cannot be retrieved. + +If your key is compromised or you lose it, open the action in the automation editor and click **Regenerate secret**. The old key stops working immediately. Update your server before regenerating or your signature verification will fail. + +**What Plane sends** + +Every request includes these headers: + +| Header | Value | +|---|---| +| `Content-Type` | `application/json` | +| `User-Agent` | `Autopilot` | +| `X-Plane-Delivery` | Unique ID for this delivery attempt | +| `X-Plane-Event` | The automation event that triggered the action | +| `X-Plane-Signature` | HMAC-SHA256 signature of the request body | + +Custom headers you add are merged in. You cannot override the reserved headers listed above. + +**Verifying the payload** + +Use the `X-Plane-Signature` header to confirm the request came from Plane and wasn't tampered with. Compute an HMAC-SHA256 digest of the raw request body bytes using your secret key and compare it to the header value. + +```python +import hashlib +import hmac + +def verify_webhook(request_body_bytes: bytes, secret: str, signature_header: str) -> bool: + expected = hmac.new( + secret.encode("utf-8"), + request_body_bytes, + hashlib.sha256, + ).hexdigest() + return hmac.compare_digest(expected, signature_header) +``` + +Use raw request body bytes - not a parsed or re-serialized version - or the signature will not match. + +**Delivery behavior** + +Plane makes a single attempt with a 30-second timeout. If the request fails or times out, it is not retried. Check your automation's Activity log to see whether the delivery succeeded and what response your server returned. + #### Run script Runs a saved script from your [Plane Runner](/automations/plane-runner) library. You pick the script from a dropdown. This is the only action available when using a scheduled trigger. @@ -184,9 +242,9 @@ Runs a saved script from your [Plane Runner](/automations/plane-runner) library. ### How automations run -Every time something changes in Plane — a work item is created, a state changes, a comment is posted — Plane checks whether any of your enabled automations should respond. If a trigger matches, Plane evaluates any conditions you've set. If those pass, it runs the actions in order. +Every time something changes in Plane - a work item is created, a state changes, a comment is posted - Plane checks whether any of your enabled automations should respond. If a trigger matches, Plane evaluates any conditions you've set. If those pass, it runs the actions in order. -That's the whole flow: something happens → conditions are checked → actions run. If a condition doesn't match, nothing happens and the automation sits quietly. If an action runs into a problem, Plane stops there and marks that run as failed — you can see exactly what happened in the Activity tab. +That's the whole flow: something happens → conditions are checked → actions run. If a condition doesn't match, nothing happens and the automation sits quietly. If an action runs into a problem, Plane stops there and marks that run as failed - you can see exactly what happened in the Activity tab. Each event is only processed once per automation, so you won't end up with the same action firing twice on the same work item. @@ -194,15 +252,15 @@ Each event is only processed once per automation, so you won't end up with the s The distinction comes down to scope and reuse. -**Project automations** are the right choice when the rule is specific to one project. They're simpler to configure — the states, labels, and members you pick from are all scoped to that project. +**Project automations** are the right choice when the rule is specific to one project. They're simpler to configure - the states, labels, and members you pick from are all scoped to that project. -**Workspace automations** are the right choice when you want the same behavior across multiple projects. Instead of recreating the same automation in five different places, you define it once and choose which projects it applies to — all of them, or just a specific subset. +**Workspace automations** are the right choice when you want the same behavior across multiple projects. Instead of recreating the same automation in five different places, you define it once and choose which projects it applies to - all of them, or just a specific subset. -Either way, automations always act on individual work items. Workspace automations aren't doing anything different — they're just defined once and applied more broadly. +Either way, automations always act on individual work items. Workspace automations aren't doing anything different - they're just defined once and applied more broadly. ### Automation bot -Every custom automation acts through its own dedicated bot account. When an automation changes a field or posts a comment, the activity log shows it came from "Automation Bot" — not from any person on your team. +Every custom automation acts through its own dedicated bot account. When an automation changes a field or posts a comment, the activity log shows it came from "Automation Bot" - not from any person on your team. There are two reasons this matters: @@ -212,32 +270,32 @@ There are two reasons this matters: ### Why scheduled automations only run scripts -Most automations respond to something happening — a trigger gives them a specific work item to act on. Scheduled automations are different. They fire at a time you set, not because of any particular event. +Most automations respond to something happening - a trigger gives them a specific work item to act on. Scheduled automations are different. They fire at a time you set, not because of any particular event. -Since there's no work item that kicked off the run, Plane has nothing to apply a property change or comment to. That's why the only available action for scheduled automations is Run script. The script defines the logic — what to look for, which items to act on, and what to do with them. +Since there's no work item that kicked off the run, Plane has nothing to apply a property change or comment to. That's why the only available action for scheduled automations is Run script. The script defines the logic - what to look for, which items to act on, and what to do with them. Scheduled automations check whether they're due roughly every 5 minutes. The time you configure follows your project's timezone, falling back to the workspace timezone, then UTC. ### Why your trigger isn't enough on its own -Triggers tell Plane _what type of event_ to watch for — not which work items to care about. A "state changed" trigger fires for every single state change in the project, across every work item, regardless of type, priority, or who it's assigned to. +Triggers tell Plane _what type of event_ to watch for - not which work items to care about. A "state changed" trigger fires for every single state change in the project, across every work item, regardless of type, priority, or who it's assigned to. Without conditions, an action like "set priority to Urgent" would run on every state change in the project. That's almost never what you want. -Conditions are what make an automation surgical. They let you say "only run this when the work item is a Bug, assigned to this person, with no due date set" — whatever combination of criteria actually defines the case you're building for. +Conditions are what make an automation surgical. They let you say "only run this when the work item is a Bug, assigned to this person, with no due date set" - whatever combination of criteria actually defines the case you're building for. -One thing worth knowing: when a work item is first created, some fields like assignees and labels can take a moment to register, even if someone filled them in during creation. Plane handles this — it checks the latest state of those fields before evaluating your conditions, so a filter like "assignee is X" on a creation trigger will work as expected. +One thing worth knowing: when a work item is first created, some fields like assignees and labels can take a moment to register, even if someone filled them in during creation. Plane handles this - it checks the latest state of those fields before evaluating your conditions, so a filter like "assignee is X" on a creation trigger will work as expected. ## Common use cases Some common things people use automations for. -- **State management.** Automatically move work items through your workflow when something changes — for example, transition a work item to "In Review" when an assignee is added, or back to "Backlog" when an assignee is removed. +- **State management.** Automatically move work items through your workflow when something changes - for example, transition a work item to "In Review" when an assignee is added, or back to "Backlog" when an assignee is removed. -- **Triage and routing.** Make sure new work lands in the right place without manual intervention — for example, assign a default owner whenever a specific work item type is created, or apply a label to every incoming bug so nothing slips through untagged. +- **Triage and routing.** Make sure new work lands in the right place without manual intervention - for example, assign a default owner whenever a specific work item type is created, or apply a label to every incoming bug so nothing slips through untagged. -- **Priority escalation.** React to signals that indicate urgency — for example, automatically mark a work item as Urgent when a specific label is applied, or raise priority when it gets reassigned to a senior team member. +- **Priority escalation.** React to signals that indicate urgency - for example, automatically mark a work item as Urgent when a specific label is applied, or raise priority when it gets reassigned to a senior team member. -- **Contextual reminders.** Surface the right information at the right moment — for example, post an internal comment with a checklist when a work item enters "Ready for QA," or flag missing information when a work item is created without an assignee. +- **Contextual reminders.** Surface the right information at the right moment - for example, post an internal comment with a checklist when a work item enters "Ready for QA," or flag missing information when a work item is created without an assignee. -- **Scheduled operations.** Run scripts on a timer to handle things that don't map to a single event — for example, sweep stale items weekly, sync data to an external tool nightly, or generate a status comment on open items every Monday morning. +- **Scheduled operations.** Run scripts on a timer to handle things that don't map to a single event - for example, sweep stale items weekly, sync data to an external tool nightly, or generate a status comment on open items every Monday morning. From 480a4c4cfbf4e2398c6053650a690238a846ba7a Mon Sep 17 00:00:00 2001 From: danciaclara Date: Thu, 4 Jun 2026 19:02:41 +0530 Subject: [PATCH 2/3] Update Releases and plan tags in some features --- docs/automations/overview.md | 2 +- .../issues/plane-query-language.md | 2 +- docs/core-concepts/pages/editor-blocks.md | 2 +- docs/releases.md | 202 +++++++++++++----- 4 files changed, 156 insertions(+), 52 deletions(-) diff --git a/docs/automations/overview.md b/docs/automations/overview.md index 5a35964..359d5c9 100644 --- a/docs/automations/overview.md +++ b/docs/automations/overview.md @@ -40,7 +40,7 @@ Auto-close moves unfinished work items — those in Backlog, Unstarted, or Start 3. Set the **Auto-close work items that are inactive for** duration — for example, 1 month. 4. Choose the **Auto-close status** — the state that inactive work items will be moved to (e.g., Cancelled). -### Set up due date reminders +### Set up due date reminders Plane sends in-app and email notifications to assignees and subscribers when a work item's due date is approaching. diff --git a/docs/core-concepts/issues/plane-query-language.md b/docs/core-concepts/issues/plane-query-language.md index 02587d9..a54643b 100644 --- a/docs/core-concepts/issues/plane-query-language.md +++ b/docs/core-concepts/issues/plane-query-language.md @@ -3,7 +3,7 @@ title: Plane Query Language description: Filter work items using text-based queries with Plane Query Language (PQL). --- -# Plane Query Language (PQL) +# Plane Query Language (PQL) Plane Query Language (PQL) lets you filter work items using text-based queries. Write structured expressions to quickly find exactly what you need. diff --git a/docs/core-concepts/pages/editor-blocks.md b/docs/core-concepts/pages/editor-blocks.md index f7b958b..2c78273 100644 --- a/docs/core-concepts/pages/editor-blocks.md +++ b/docs/core-concepts/pages/editor-blocks.md @@ -162,7 +162,7 @@ Both modes feature a consistent toolbar with **Save** and **Exit** buttons, maki Creates visually distinct sections with customizable icons and colors for highlighting warnings, tips , and calls-to-action. -## AI block +## AI block Generate or transform content directly within your pages using AI. The AI Block lets you draft new content, summarize existing text, or run custom prompts without leaving the editor. diff --git a/docs/releases.md b/docs/releases.md index fc161d6..ae17b2c 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -5,61 +5,82 @@ description: Group work items under named versions, track delivery progress, and # Releases -Releases give your workspace a dedicated space to group work items under a named version, monitor delivery progress, and publish a changelog. Whether you're shipping a minor patch or a major feature launch, Releases keep your team aligned on what's going in and how much is done. +A release is how you communicate what your team is shipping and when. It groups work items from across your workspace into a named, versioned deliverable - with a target date, a lead, a changelog, and a clear status that tells everyone whether this version is in progress, out the door, or cancelled. -## How Releases work +![Enable releases](https://media.docs.plane.so/releases/enable-releases.webp#hero) -A release is a named version that pulls together work items from any project in your workspace. As those work items move through their states, the release tracks progress automatically. When you're ready to ship, the release becomes the place to publish a changelog for the rest of the team. +Releases live at the workspace level, not the project level. That means a single release can pull in work items from multiple projects. A release for "v2.3.0" might include a backend fix from your API project, a UI change from your web project, and a docs update from your content project - all tracked together in one place. -Releases live at the workspace level. This means a single release can span multiple projects — useful when a feature launch involves work across multiple projects. +This is the key distinction between releases and cycles. Cycles are sprint containers - time-boxed, project-scoped, for managing ongoing development. Releases are version containers - for grouping and communicating deliverables across projects, regardless of which cycle the work was done in. -![Release activation](https://media.docs.plane.so/releases/activate-releases.webp#hero) +## Set up releases for your workspace -## Activate Releases +Releases must be enabled at the workspace level before anyone can use them. -> **Role**: Workspace Admin - -1. Go to **Workspace Settings > Releases**. +1. Go to **Workspace Settings → Releases**. 2. Toggle on **Enable Releases**. -Once enabled, **Releases** appears in the workspace sidebar for all members. Disabling the toggle hides the section but preserves all existing data — re-enabling restores everything. +Once enabled, workspace members have view access to releases in the sidebar. Owners and Admins can create, edit, and delete them. + +### Manage release tags + +Tags are version identifiers shared across all releases in the workspace. Create them before you start creating releases, or add them as needed. + +**To create a tag:** + +1. Go to **Workspace Settings → Releases → Release tags**. +2. Click **Add Tag**. +3. Enter a version string (e.g., `v2.3.0`). +4. Save. + +**To edit or delete a tag:** + +1. Go to **Workspace Settings → Releases → Release tags**. +2. Click **···** on the tag row and select **Edit tag** or **Delete tag**. -## Set up tags and labels +Deleting a tag removes it from any releases it was assigned to. -> **Role**: Workspace Admin +### Manage labels -Before your team starts creating releases, set up tags and labels to keep things organized. Both are managed from **Workspace Settings > Releases** and available across the workspace when creating or editing a release. +Labels let you categorize releases across the workspace - for example by team, platform, or release type. -### Release tags +**To create a label:** -Tags categorize releases across your workspace — useful for filtering by type, environment, or team. Switch to the **Release tags** tab and click **Add Tag** to create one. +1. Go to **Workspace Settings → Releases → Labels**. +2. Click **Add Label**. +3. Enter a name and choose a color. +4. Save. -### Labels +**To reorder labels:** Drag the label rows into the order you want. -Labels organize releases visually with a name and color. These are separate from the project-level work item labels. Switch to the **Labels** tab and click **Add Label** to create one. +**To edit or delete a label:** + +1. Go to **Workspace Settings → Releases → Labels**. +2. Click **···** on the label row and select **Edit label** or **Delete label**. ## Create a release ![Create Releases](https://media.docs.plane.so/releases/create-releases.webp#hero) -1. Click **Releases** in the workspace sidebar. +1. Go to **Releases** in the workspace sidebar. 2. Click **Add Release**. 3. Fill in the release details: | Field | Description | | --------------- | --------------------------------------------------------------------------------- | - | **Title** | Required. A short name for the release — for example, "v2.4 — Dashboard refresh." | - | **Description** | Goals, notes, or relevant links. | - | **Status** | Unreleased (default), Released, or Cancelled. | - | **Tag** | One or more tags from workspace settings. | - | **Labels** | One or more labels from workspace settings. | - | **Target date** | Planned ship date. | - | **Lead** | Responsible owner, selected from workspace members. | + | **Name** | Identifies the release in the list and throughout the workspace. Release names must be unique within the workspace. | + | **Description** | A rich text field for context - background, goals, or any notes the team needs before the work starts. | + | **Status** | Tracks where the release is in its lifecycle. Values: Unreleased (default), Released, or Cancelled. | + | **Tag** | A version identifier - for example, `v2.3.0` or `2024-Q4`. Tags are shared across all releases in the workspace. A release can have one tag. | + | **Labels** | Let you categorize and organize releases. A release can have multiple labels. | + | **Target date** | The planned release date - when you intend to ship. This is separate from the actual release date, which you can record once the work is done. | + | **Lead** | The person responsible for the release. One user, visible in the release list.| 4. Click **Create Release**. You'll land on the release detail page, where you can start adding scope and writing the changelog. + ## Work with a release Each release has three tabs: **Overview**, **Scope**, and **Changelog**. @@ -68,62 +89,145 @@ Each release has three tabs: **Overview**, **Scope**, and **Changelog**. The Overview tab shows the release description, all selected properties, and a live progress tracker. -The progress bar fills proportionally as work items in the release are completed. Counters display completed work items (e.g., 18/22 — 82%), pending work items, and cancelled work items. +The progress bar fills proportionally as work items in the release are completed. Counters display completed work items (e.g., 18/22 - 82%), pending work items, and cancelled work items. -Click any property chip — Tag, Label, Lead, or Target date — to edit it inline. Click **Click to add description** to write or update the release description. +Click any property chip - Tag, Label, Lead, or Target date - to edit it inline. Click **Click to add description** to write or update the release description. ![Release overview](https://media.docs.plane.so/releases/release-overview.webp#hero) + +#### Track progress + +Plane tracks three counts for every release based on the current state of linked work items: + +- **Completed work items** - work items whose state group is Completed +- **Cancelled work items** - work items whose state group is Cancelled +- **Pending work items** - everything else (Backlog, Unstarted, Started) + +These update automatically as your team moves work items through states. The progress indicator in the release list and on the Overview tab reflects the completed count against the total. + +Plane does not automatically change a release's status when all work items are completed. You mark the release as Released manually when you're ready. + #### Release status A release moves through three statuses that reflect where it is in its lifecycle: -- **Unreleased** — the default status when a release is created. Work is still in progress, and the scope and changelog are being built out. -- **Released** — the release has shipped. Use this to mark the release as complete and signal to your team that it's out. -- **Cancelled** — the release was abandoned. Use this when a planned release is no longer going forward, so the scope and history are preserved without cluttering your active releases. +- **Unreleased** - the default status when a release is created. Work is still in progress, and the scope and changelog are being built out. +- **Released** - the release has shipped. Use this to mark the release as complete and signal to your team that it's out. +- **Cancelled** - the release was abandoned. Use this when a planned release is no longer going forward, so the scope and history are preserved without cluttering your active releases. Click the status chip on the Overview tab to change it. The Releases list groups releases by their status, so updating this keeps your list organized and makes it easy to see what's active, shipped, or cancelled. +You can also set the actual release date here to record when the version shipped. + +Cancelled releases remain in the list and all their data is preserved. Work items linked to a cancelled release are not affected. + ### Scope -The Scope tab lists all work items attached to the release, categorized by [state group](/core-concepts/issues/states#state-groups). This is the source of truth for what's in the release. +The scope of a release is the set of work items it contains - everything your team needs to ship for this version. Work items come from any project in the workspace. There is no restriction to a single project. + +![Release scope](https://media.docs.plane.so/releases/release-scope.webp#hero) Click **Add work items** to search and attach items by title or ID. Work items from any project in the workspace can be scoped to a release. To remove an item, hover over it and click the remove icon. -A work item's existing state drives the progress calculation automatically — you don't need to mark anything as "done in release" separately. -![Release scope](https://media.docs.plane.so/releases/release-scope.webp#hero) +#### Add work items to a release -### Changelog +1. Open the release and go to the **Scope** tab. +2. Click **Add work items**. +3. Search for work items by name or identifier. +4. Select the items you want to include. +5. Click **Add selected work items**. -The Changelog tab provides a rich text editor where you write and publish a summary of what changed in the release. +You can add work items from any project in the workspace. -The editor supports all the same [blocks](/core-concepts/pages/editor-blocks) available in Pages and Wiki. Changes save automatically as you type, and the changelog is visible to all workspace members who can access the release. +#### Remove a work item from a release + +1. Open the release and go to the **Scope** tab. +2. Find the work item you want to remove. +3. Click the **···** menu on the work item row and select **Remove from release**. + +The work item remains in its project - only the link to the release is removed. + +A work item's existing state drives the progress calculation automatically - you don't need to mark anything as "done in release" separately. + +Adding a work item to a release does not move it, reassign it, or change its state. It creates a link. The work item stays in its project, continues through its normal workflow, and appears in the release's Scope view alongside everything else you're tracking for this version. + +Removing a work item from a release removes the link only. The work item remains in its project. + +### Changelog + +The **Changelog** tab is a separate rich text document for recording what changed in this version - new features, fixes, breaking changes, anything you want to communicate to users or stakeholders. It's independent from the description and intended as the outward-facing record of the release. Edit it any time before or after shipping. The changelog is blank by default. ![Release changelog](https://media.docs.plane.so/releases/release-changelog.webp#hero) +The editor supports all the same [blocks](/core-concepts/pages/editor-blocks) available in Pages and Wiki. Changes save automatically as you type, and the changelog is visible to all workspace members who can access the release. + :::tip Use the Scope tab to audit completed work items, then use the Changelog tab to write polished, user-facing notes based on that list. ::: -## Tag work items with a Release property +## Work with releases from a work item -Plane supports **Release picker** as a custom property type on work items. This makes the release a first-class attribute on any work item, so members can assign work to a release without navigating to the Scope tab. +### The Releases property -### Add the Release property +Every work item has a **Releases** property in its detail panel, in the same section as Cycle and Module. It works in both directions - you can link a work item to a release from the work item itself, not just from the Releases page. Whatever you do from either side produces the same result: a link between the work item and the release. -> **Role**: Project Admin +A work item can belong to more than one release. If you're shipping the same fix in both `v2.3.1` (a patch) and `v3.0.0` (the next major), you can add both releases to the same work item. The work item appears in the scope of each release and counts toward the progress of each. -To add the Release property to a work item type: +The Releases property is only visible when releases are enabled for your workspace. If you don't see it in the detail panel, check that releases have been turned on in **Workspace Settings → Releases**. -1. Go to **Project Settings > Work item Types**. -2. Select the work item type you want to extend. -3. Add a custom property of type **Release**. +#### Assign a release from the work item detail panel -Once added, the **Release picker** field appears in the work item detail view. Any project member can set which release a work item belongs to directly from there, and the work item will automatically appear in that release's Scope tab. +1. Open the work item. +2. In the sidebar, find the **Releases** property under the project structure section. +3. Click the property to open the release picker. +4. Search for or select the release you want to link. +5. The link is saved immediately. + +To link multiple releases, open the picker again and select another release. Each selection adds to the list without removing the previous ones. + +#### Remove a release from the work item detail panel + +1. Open the work item. +2. In the sidebar, find the **Releases** property. +3. Click on the release you want to remove. +4. Deselect it from the picker. + +Removing the release from the work item is the same as removing the work item from the release's Scope tab - the work item remains in its project, unchanged. + +#### Assign a release inline from list, board, and table layouts + +You do not need to open the detail panel to assign a release. In any project view, you can update the Releases property directly on the work item row or card. + +**In list layout**: Click the Releases property on the work item row. If the column is not visible, enable it from **Display → Properties → Releases**. + +**In table layout**: Click the Releases cell in the work item row. The release picker opens inline. Add or remove releases without leaving the spreadsheet. + +**In board (kanban) layout**: Click the Releases indicator on the work item card. If releases are not showing on cards, enable them from **Display → Properties → Releases**. + +### The Release picker custom property + +There is a second, separate way releases can appear on a work item: as a **Release picker** custom property added to a work item type. + +When a workspace admin adds a Release picker property to a work item type in **Workspace Settings → Work Item Types**, work items of that type get a multi-select field for picking one or more releases. It looks and behaves like the built-in Releases property - searchable dropdown, multi-select - but it is a custom field, not a system field. + +For how to create a Release picker property on a work item type, see [Work item types](/work-items/project-work-item-types#add-custom-properties). + +## Manage releases + +### Edit a release + +1. Go to **Releases** in the workspace sidebar. +2. Click **···** on the release row and select **Edit**, or open the release and update properties directly from the **Overview** tab. +3. Change name, status, dates, lead, tag, labels, or description as needed. + +### Delete a release + +1. Go to **Releases** in the workspace sidebar. +2. Click **···** on the release row and select **Delete**. +3. Confirm. + +Deleting a release removes it permanently. Work items that were linked to the release are not deleted - they remain in their projects. -With release as a work item attribute, you can group, filter, and build dashboard views around release milestones, giving leadership visibility into delivery velocity per release. -:::tip -When importing from Jira, Fix Version and Affects Version fields map cleanly to the Release property. Your release tagging data carries over without manual re-tagging. -::: From 43eb09a41b5811395c0cbed100039f26f7d16566 Mon Sep 17 00:00:00 2001 From: danciaclara Date: Thu, 4 Jun 2026 19:08:49 +0530 Subject: [PATCH 3/3] formatting fixes --- docs/automations/custom-automations.md | 26 +++++++++++++------------- docs/releases.md | 23 +++++++++-------------- 2 files changed, 22 insertions(+), 27 deletions(-) diff --git a/docs/automations/custom-automations.md b/docs/automations/custom-automations.md index 1ee887f..0c3a52f 100644 --- a/docs/automations/custom-automations.md +++ b/docs/automations/custom-automations.md @@ -185,11 +185,11 @@ This is different from workspace webhooks, which fire on any matching event acro **Configuration** -| Field | Required | Notes | -|---|---|---| -| URL | Yes | Must be a publicly reachable `http://` or `https://` address. Local and private network addresses are not accepted. | -| Secret key | Auto-generated | Generated when you save the action. Shown once in plain text - copy it before leaving. After that it appears masked as `plane_wh_••••XXXX`. | -| Custom headers | No | Up to 20 headers. Mark a header as secret to store its value encrypted - the value won't be returned in subsequent reads. | +| Field | Required | Notes | +| -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| URL | Yes | Must be a publicly reachable `http://` or `https://` address. Local and private network addresses are not accepted. | +| Secret key | Auto-generated | Generated when you save the action. Shown once in plain text - copy it before leaving. After that it appears masked as `plane_wh_••••XXXX`. | +| Custom headers | No | Up to 20 headers. Mark a header as secret to store its value encrypted - the value won't be returned in subsequent reads. | **The secret key** @@ -201,13 +201,13 @@ If your key is compromised or you lose it, open the action in the automation edi Every request includes these headers: -| Header | Value | -|---|---| -| `Content-Type` | `application/json` | -| `User-Agent` | `Autopilot` | -| `X-Plane-Delivery` | Unique ID for this delivery attempt | -| `X-Plane-Event` | The automation event that triggered the action | -| `X-Plane-Signature` | HMAC-SHA256 signature of the request body | +| Header | Value | +| ------------------- | ---------------------------------------------- | +| `Content-Type` | `application/json` | +| `User-Agent` | `Autopilot` | +| `X-Plane-Delivery` | Unique ID for this delivery attempt | +| `X-Plane-Event` | The automation event that triggered the action | +| `X-Plane-Signature` | HMAC-SHA256 signature of the request body | Custom headers you add are merged in. You cannot override the reserved headers listed above. @@ -230,7 +230,7 @@ def verify_webhook(request_body_bytes: bytes, secret: str, signature_header: str Use raw request body bytes - not a parsed or re-serialized version - or the signature will not match. -**Delivery behavior** +**Delivery behavior** Plane makes a single attempt with a 30-second timeout. If the request fails or times out, it is not retried. Check your automation's Activity log to see whether the delivery succeeded and what response your server returned. diff --git a/docs/releases.md b/docs/releases.md index ae17b2c..bc5767a 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -66,21 +66,20 @@ Labels let you categorize releases across the workspace - for example by team, p 2. Click **Add Release**. 3. Fill in the release details: - | Field | Description | - | --------------- | --------------------------------------------------------------------------------- | - | **Name** | Identifies the release in the list and throughout the workspace. Release names must be unique within the workspace. | - | **Description** | A rich text field for context - background, goals, or any notes the team needs before the work starts. | - | **Status** | Tracks where the release is in its lifecycle. Values: Unreleased (default), Released, or Cancelled. | - | **Tag** | A version identifier - for example, `v2.3.0` or `2024-Q4`. Tags are shared across all releases in the workspace. A release can have one tag. | - | **Labels** | Let you categorize and organize releases. A release can have multiple labels. | - | **Target date** | The planned release date - when you intend to ship. This is separate from the actual release date, which you can record once the work is done. | - | **Lead** | The person responsible for the release. One user, visible in the release list.| + | Field | Description | + | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | + | **Name** | Identifies the release in the list and throughout the workspace. Release names must be unique within the workspace. | + | **Description** | A rich text field for context - background, goals, or any notes the team needs before the work starts. | + | **Status** | Tracks where the release is in its lifecycle. Values: Unreleased (default), Released, or Cancelled. | + | **Tag** | A version identifier - for example, `v2.3.0` or `2024-Q4`. Tags are shared across all releases in the workspace. A release can have one tag. | + | **Labels** | Let you categorize and organize releases. A release can have multiple labels. | + | **Target date** | The planned release date - when you intend to ship. This is separate from the actual release date, which you can record once the work is done. | + | **Lead** | The person responsible for the release. One user, visible in the release list. | 4. Click **Create Release**. You'll land on the release detail page, where you can start adding scope and writing the changelog. - ## Work with a release Each release has three tabs: **Overview**, **Scope**, and **Changelog**. @@ -95,7 +94,6 @@ Click any property chip - Tag, Label, Lead, or Target date - to edit it inline. ![Release overview](https://media.docs.plane.so/releases/release-overview.webp#hero) - #### Track progress Plane tracks three counts for every release based on the current state of linked work items: @@ -130,7 +128,6 @@ The scope of a release is the set of work items it contains - everything your te Click **Add work items** to search and attach items by title or ID. Work items from any project in the workspace can be scoped to a release. To remove an item, hover over it and click the remove icon. - #### Add work items to a release 1. Open the release and go to the **Scope** tab. @@ -229,5 +226,3 @@ For how to create a Release picker property on a work item type, see [Work item 3. Confirm. Deleting a release removes it permanently. Work items that were linked to the release are not deleted - they remain in their projects. - -