How-to guide For operators

Push to a tracker

Push the work breakdown the build step derives from the accepted data contract into Azure DevOps or Jira, instead of a delivery lead retyping it by hand.

Before you start

An accepted data contract, and at least one build — the plan is derived from the agreement, so there is nothing to push before then.
For Azure DevOps: a personal access token with Work Items (Read & write) and nothing else — no Code, no Build, no Release scope — plus the organisation and the team project.
For Jira: an API token from id.atlassian.com (not a password) with Create issues and Link issues in the target project, and the account email it belongs to. The token inherits that account's project permissions.
The release.build permission — see Roles and permissions.

Steps

Choose the tracker and set its credentials.

export DPF_TRACKER=ado                       # ado | jira | unset
export DPF_ADO_ORG=acme                      # dev.azure.com/<org>
export DPF_ADO_PROJECT=Data                  # the team project
export DPF_ADO_PAT=…                         # Work Items (Read & write)
export DPF_ADO_WORK_ITEM_TYPE='User Story'   # optional
export DPF_ADO_AREA_PATH='Data\Platform'     # optional, must already exist

export DPF_TRACKER=jira
export DPF_JIRA_URL=https://acme.atlassian.net
export DPF_JIRA_PROJECT=DATA                 # the project key
export DPF_JIRA_EMAIL=rae@acme.example       # the account the token belongs to
export DPF_JIRA_TOKEN=…                      # an API token, not a password
export DPF_JIRA_ISSUE_TYPE=Story             # optional, default Story

DPF_TRACKER may be left unset: whichever backend has credentials is used, and Azure DevOps' vocabulary is the fallback when neither does. A value that is neither ado nor jira falls back the same way rather than failing, and the Connections page says which one it fell back to.

Open Push to <tracker> on the build step. It opens on the dry run — every item that would be created, the work item type the board files it under, and each dependency link in the tracker's own words: Azure DevOps says Predecessor, Jira says is blocked by.
Select Push N items to <tracker>. The form carries a fingerprint of what was on screen; if the agreement changes between the preview and the push, the push is refused and the new plan is shown instead of being confirmed by proxy.

Check that it worked

Each pushed item shows its ticket number, linked into the tracker. Re-opening the page after a later build shows the same numbers against items already there, marked not pushed again — a ticket is stored once, in tracker_items, and reused to resolve everybody else's dependency links, so a plan pushed in two halves still ends up wired together.

With nothing configured, the page still walks the whole flow: ticket numbers are minted — derived from the product and the item, so they do not change on reload — and every one is marked simulated. Nothing is sent anywhere and no ticket exists.

What is not supported yet

Neither has run against a real organisation. Both are listed on the Connections page as mock-ups: written to Microsoft's and Atlassian's published shapes and tested as data, which is not the same as having created a work item in somebody's backlog.
Create only. A second push skips an item that already has a ticket; it does not update a title that changed, close a ticket for a dropped item, or read state back.
A push that fails partway is reported, not rolled back. The items created before the failure exist, so they are recorded, and the page says how many got in.
Azure DevOps Server (on-premises) is not supported — only dev.azure.com.
The work item type is not validated before the call. Agile calls it a User Story, Scrum a Product Backlog Item, Basic an Issue; asking for one the process does not have fails with the service's own message.
No sprint, iteration, assignee, estimate or parent epic. Mapping a size (S/M/L) onto story points would be inventing an estimate nobody gave.
No OAuth. A PAT or an API token in an environment variable, as with Databricks.

If it does not work

Symptom	Fix
The push button is disabled, "Nothing left to push"	Every item already carries a ticket — there is nothing to do.
Jira fails to create an issue	The token inherits its account's own project permissions; one minted by somebody without create rights in the project fails with Jira's own message.
The page shows the old plan after accepting a new agreement	Expected — re-open the build step so the plan is derived again, then push.

Configuration — every tracker variable.
Enforce the agreement in Databricks — the other artefact pushed outward from an agreement.