Read on newly released AI assisted Insights
flxbl docs
Ctrlk
Learn CD Concepts using LabsslackGitHub
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Work Items

Update IssueOps request from workflow callback

post

Called by the workflow callback flow to update the IssueOps request status. Maps callback events to request statuses:

  • started → in_progress

  • completed → completed (or closed if work item was closed)

  • failed → failed

  • rejected → completed

  • cancelled → closed

Uses findOrCreate reconciliation — if the request was not tracked at creation time, it will be backfilled.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
eventstring · enumRequired

Callback event type

Example: completedPossible values:
platformstring · enumRequired

Callback provider type

Example: githubPossible values:
workItemKeystringRequired

Work item key (issue number for GitHub, work item ID for Azure DevOps)

Example: 42
projectIdentifierstringRequired

Project identifier (owner/repo)

Example: flxbl-io/sf-core
closedbooleanOptional

Whether the work item was closed as part of this callback

Example: true
Responses
200

Request status updated

No content
post/sfp/api/work-items/requests/callback
No content

List IssueOps requests

get

List and filter IssueOps requests. projectIdentifier is optional — when omitted, the response spans every project the caller can access (tenant-wide view).

Key Use Cases

  • Tenant-wide in-flight queue: ?status=open,in_progress

  • In-flight requests for a project: ?projectIdentifier=x&status=open,in_progress

  • Requests for a release candidate: ?releaseCandidate=core:RC-JAN25-01

  • Failed release requests: ?taskType=execute-release&status=failed

The status parameter supports comma-separated values for filtering multiple statuses at once.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
projectIdentifierstringOptional

Project identifier to scope results. When omitted, returns requests across every project the caller can access.

Example: flxbl-io/sf-core
statusstringOptional

Filter by status. Comma-separated for multiple: open,in_progress

Example: open,in_progress
platformstring · enumOptional

Filter by platform

Possible values:
taskTypestringOptional

Filter by task type (e.g., execute-release, request-sandbox-create)

Example: execute-release
releaseCandidatestringOptional

Filter by release candidate (e.g., core:RC-JAN25-01). Returns all requests targeting this RC.

Example: core:RC-JAN25-01
repositoryIdentifierstringOptional

Filter by target repository identifier

Example: flxbl-io/sf-core
createdBystringOptional

Filter by actor email

Example: user@example.com
sincestringOptional

Only requests created after this ISO 8601 timestamp

Example: 2026-01-01T00:00:00.000Z
limitnumberOptional

Maximum number of results

Default: 50Example: 50
offsetnumberOptional

Offset for pagination

Default: 0Example: 0
Responses
200

List of IssueOps requests

No content
get/sfp/api/work-items/requests
No content

Get an IssueOps request by ID

get

Get a single IssueOps request by its UUID.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired
Responses
200

IssueOps request details

No content
get/sfp/api/work-items/requests/{id}
No content

Create work item with embedded task payload

post

Creates a work item (GitHub Issue or Azure DevOps Work Item) with an embedded task payload for IssueOps automation.

How It Works

  1. Provider Detection: The provider is determined by the project's configuration.workItems.provider setting

  2. Authentication: The signed-in user's provider OAuth token is used from the authToken field (required)

  3. Payload Embedding: The task payload is embedded in the work item body for later extraction by automation

Prerequisites

1. Project Configuration

The project must have workItems.provider configured:

# Set via CLI
sfp server project update -r flxbl-io/sf-core \
  -p configuration.workItems \
  -v '{"provider": "azure-devops"}'

# Or via API
PATCH /projects/flxbl-io%2Fsf-core
{
  "property": "configuration.workItems",
  "value": { "provider": "azure-devops" }
}

2. Authentication - Signed-In User Provider Token Required

The authToken field is mandatory. Work items are created using the signed-in user's provider OAuth token to ensure proper attribution and audit trail.

Why a user token is required:

  • Work items show the actual user as the creator

  • Clear audit trail of who initiated each request

  • Proper attribution for compliance and tracking

Token Requirements:

  • GitHub: OAuth provider token from login

  • Azure DevOps: OAuth provider token from login, sent to Azure DevOps as Authorization: Bearer <token>

Note: Server-stored credentials (GitHub App or Azure DevOps service principal) are not used for user-submitted work item creation to ensure proper user attribution.

Valid Task Types

Task Type
Description

request-elevated-privileges

Request temporary elevated access

request-freeze-users

Freeze users in an environment

request-unfreeze-users

Unfreeze users in an environment

request-sandbox-create

Create a new sandbox

request-sandbox-refresh

Refresh sandbox from source

request-sandbox-delete

Delete a sandbox

install-packages

Install managed/unlocked packages

install-artifacts

Install build artifacts

install-changeset

Install or validate a changeset artifact

create-patch-branch

Create a patch branch

run-apex-tests

Execute Apex tests

Flow Triggering

When triggerFlow: true is set, the endpoint will:

  1. Create the work item as usual

  2. Trigger the associated Hatchet workflow with the payload

  3. Pass the created work item as the callback destination for flow notifications

  4. Return both work item details and flow trigger results

This enables end-to-end IssueOps automation where creating a work item immediately kicks off the associated workflow.

Payload Embedding

The payload is embedded in the work item body in a format that can be extracted by automation:

  • GitHub: Embedded as HTML comment <!-- {"id": "...", ...} -->

  • Azure DevOps: Embedded in collapsible section (Azure strips HTML comments)

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
projectIdentifierstringRequired

Project identifier as registered in sfp server. Must match the project's workItems.provider configuration.

Example: flxbl-io/sf-core
titlestringRequired

Work item title. Use a descriptive prefix like [Request] for IssueOps workflows.

Example: [Request] Provision Scratch Org for Development
bodystringOptional

Work item body/description. The task payload will be appended to this.

Example: Please provision a new scratch org for the development team. Duration: 7 days
payloadobjectRequired

Task payload with id matching a registered task type. Valid types:

  • request-elevated-privileges - Request temporary elevated access
  • request-freeze-users - Freeze users in an environment
  • request-unfreeze-users - Unfreeze users
  • request-sandbox-create - Create a new sandbox
  • request-sandbox-refresh - Refresh sandbox from source
  • request-sandbox-delete - Delete a sandbox
  • install-packages - Install managed/unlocked packages
  • install-artifacts - Install build artifacts
  • install-changeset - Install or validate a changeset artifact
  • create-patch-branch - Create a patch branch
  • run-apex-tests - Execute Apex tests
  • request-a-release-to-release-envs - Request release deployment to environments (orchestrator)
  • execute-release - Execute release to a single environment
  • unbundle-release-candidate - Remove commits from a release candidate branch
Example: {"id":"request-sandbox-create","env":"dev","duration":"7"}
authTokenstringOptional

Provider OAuth access token for user attribution. Optional.

Pass it when the signed-in user already holds a provider token (social-login). When omitted, the server resolves the caller's linked provider identity (device flow) and acts as them — the token stays server-side. If the caller has no usable linked identity, the request fails with HTTP 428 PROVIDER_IDENTITY_RELINK_REQUIRED; the client should run the device flow (/user/provider-identity/device/start → device/poll) and retry.

GitHub: OAuth provider token from login Azure DevOps: OAuth provider token from login, sent to Azure DevOps as Authorization: Bearer <token>

Example: provider-oauth-access-token
labelsstring[]Optional

Labels/tags to apply to the work item. Used for filtering and automation triggers.

Example: ["issueops","sandbox","automation"]
assigneesstring[]Optional

Assignees for the work item.

GitHub: Array of GitHub usernames Azure DevOps: Array of email addresses

Example: ["john-doe"]
milestonestringOptional

GitHub only: Milestone number or title to associate with the issue

Example: Sprint 23
workItemTypestringOptional

Azure DevOps only: Work item type. Common types depend on the process template:

  • Basic: Issue, Epic, Task
  • Agile: Bug, User Story, Task, Epic
  • Scrum: Bug, Product Backlog Item, Task, Epic
Example: Task
areaPathstringOptional

Azure DevOps only: Area path for categorization. Use backslashes to separate hierarchy.

Example: sf-core\Team Alpha
iterationPathstringOptional

Azure DevOps only: Iteration path for sprint assignment. Use backslashes to separate hierarchy.

Example: sf-core\Sprint 23
prioritynumber · min: 1 · max: 4Optional

Azure DevOps only: Priority level (1 = highest, 4 = lowest)

Example: 2
organizationUrlstringOptional

Azure DevOps only: Organization URL.

Optional if configured in project settings. The server first checks the project's configuration.workItems.organizationUrl. Only provide this to override the project configuration or if not configured at the project level.

Configure at project level via:

PATCH /projects/{identifier}
{ "property": "configuration.workItems", "value": { "organizationUrl": "https://dev.azure.com/org", "project": "proj" } }
Example: https://dev.azure.com/flxbl-io
projectstringOptional

Azure DevOps only: Project name within the organization.

Optional if configured in project settings. The server first checks the project's configuration.workItems.project. Only provide this to override the project configuration or if not configured at the project level.

Example: sf-core
triggerFlowbooleanOptional

Controls whether to trigger the Hatchet workflow immediately after creating the work item.

When to set triggerFlow: true:

  • You want to trigger the flow immediately without waiting for webhook events
  • The work item is being created programmatically (e.g., from a UI or automation)
  • You don't have IssueOps webhooks configured for label-based triggering

When to set triggerFlow: false (default):

  • You're using the IssueOps pattern where GitHub/Azure DevOps webhooks trigger flows based on labels
  • You want manual control over when the flow starts (e.g., after review)
  • The work item is for tracking purposes only

When true:

  • The flow is triggered synchronously after work item creation
  • The work item becomes the callback destination for flow notifications
  • The response includes flowExecution details with the execution ID

When false (default):

  • Only the work item is created
  • Flow must be triggered separately (via webhook, label, or manual API call)
Default: falseExample: true
Responses
201

Work item created successfully

application/json
idstringRequired

Unique identifier of the created work item

Example: 12345
keystringRequired

Human-readable key (issue number for GitHub, work item ID for Azure DevOps)

Example: 42
urlstringRequired

Direct URL to the work item in the provider's UI

Example: https://github.com/flxbl-io/sf-core/issues/42
platformstring · enumRequired

Platform where the work item was created

Example: githubPossible values:
createdAtstringRequired

ISO 8601 timestamp of when the work item was created

Example: 2025-01-20T12:00:00.000Z
post/sfp/api/work-items/with-payload

Update a work item

patch

Update a work item on the specified platform.

Supported Platforms

Platform
Requirements

github

Requires projectIdentifier (owner/repo format)

azure-devops

Uses configured integration credentials

jira

Not yet implemented

Available Updates

  • title: Update the work item title

  • body: Update the description/body

  • state: Change the state (e.g., "open", "closed" for GitHub)

  • labels: Set labels/tags

  • assignees: Set assignees

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
platformstring · enumRequired

Platform where the work item exists

Possible values:
idstringRequired

Work item ID or key

Responses
200

Work item updated successfully

No content
patch/sfp/api/work-items/{platform}/{id}
No content

Close a work item

post

Close a work item on the specified platform.

Supported Platforms

Platform
Close Behavior

github

Sets issue state to "closed". Optional comment.

azure-devops

Sets state to "Closed" with optional reason.

jira

Not yet implemented

Options

  • comment: Add a comment when closing

  • reason: Close reason (Azure DevOps only: "Completed", "Resolved", "Removed", etc.)

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
platformstring · enumRequired

Platform where the work item exists

Possible values:
idstringRequired

Work item ID or key

Responses
200

Work item closed successfully

No content
post/sfp/api/work-items/{platform}/{id}/close
No content

Get work item by ID

get

Fetch a work item by its ID. The platform is automatically determined from the project's configuration.workItems.provider setting.

ID Formats by Platform

Platform
ID Format
Example

jira

Project key + number

DP-6, PROJ-123

github

Issue number

42, 123

azure-devops

Work item ID

456, 789

Prerequisites

The project must have workItems.provider configured:

sfp server project update -r owner/repo \
  -p configuration.workItems \
  -v '{"provider": "jira"}'
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

Work item ID or key

Example: {"value":"DP-6","summary":"Jira issue key"}
Query parameters
projectIdentifierstringRequired

Project identifier (e.g., owner/repo)

Example: flxbl-io/sf-core
Responses
200

Work item retrieved successfully

application/json
anyOptionalExample: {"id":"10042","key":"DP-6","title":"Implement user authentication","description":"Add OAuth 2.0 authentication flow","type":"story","status":"In Progress","priority":"High","assignee":{"id":"user123","name":"John Doe","email":"john@example.com","avatarUrl":"https://example.com/avatar.png"},"reporter":{"id":"user456","name":"Jane Smith","email":"jane@example.com"},"labels":["backend","security"],"createdAt":"2025-01-10T08:00:00.000Z","updatedAt":"2025-01-11T14:30:00.000Z","platform":"jira","url":"https://flxbl-demo.atlassian.net/browse/DP-6","parent":{"id":"10040","key":"DP-1","title":"Authentication Epic"},"customFields":{"projectKey":"DP","projectName":"Demo Project","issueTypeId":"10001","statusId":"3"}}
get/sfp/api/work-items/{id}

List work items

get

List work items with optional filters. The platform is automatically determined from the project's configuration.workItems.provider setting.

Prerequisites

The project must have workItems.provider configured. Optionally configure boards to filter by specific boards/projects:

# Configure provider and boards (Jira project keys)
sfp server project update -r owner/repo \
  -p configuration.workItems \
  -v '{"provider": "jira", "boards": ["DP", "PROJ"]}'

# Configure provider and boards (Azure DevOps area paths)
sfp server project update -r owner/repo \
  -p configuration.workItems \
  -v '{"provider": "azure-devops", "boards": ["MyProject\\Team1"]}'

Filter Examples

# List work items (uses boards from project config)
GET /work-items?projectIdentifier=owner/repo

# Filter by status
GET /work-items?projectIdentifier=owner/repo&status=In Progress

# Filter by assignee
GET /work-items?projectIdentifier=owner/repo&assignee=john.doe

# Filter by type with limit
GET /work-items?projectIdentifier=owner/repo&type=bug&maxResults=10
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
projectIdentifierstringRequired

Project identifier (e.g., owner/repo)

Example: flxbl-io/sf-core
statusstringOptional

Filter by work item status (e.g., "To Do", "In Progress", "Done")

Example: In Progress
assigneestringOptional

Filter by assignee username or email

Example: john.doe
typestringOptional

Filter by work item type (e.g., "bug", "story", "task", "epic")

Example: story
maxResultsnumberOptional

Maximum number of results to return (1-100, default: 50)

Example: 50
Responses
200

Work items retrieved successfully

application/json
idstringOptionalExample: 10042
keystringOptionalExample: DP-6
titlestringOptionalExample: Implement user authentication
typestringOptionalExample: story
statusstringOptionalExample: In Progress
prioritystringOptionalExample: High
platformstringOptionalExample: jira
urlstringOptionalExample: https://example.atlassian.net/browse/DP-6
get/sfp/api/work-items

Last updated

Was this helpful?