Package Dependencies & Detection

A deployment package can declare the packages it needs. Deploy PyCharm Community and Athena installs Python 3.14 first, but only on machines that don't already have it. This page covers the package version label, detection rules that tell Athena whether a package is already installed, the Depends on list, the Deploy package step type, Force reinstall, and the per-agent package tree you see in deployment results. For step basics, start with Deployment Package Steps.

Where to set it up#

Open Deployments and click View All Packages (/deployments/packages), then create or edit a package. The editor has a Version, detection and dependencies section with these fields:

Detection rules#

A detection rule is a check that runs on the endpoint. If the check passes, Athena treats the package as already installed. Detection rules run in PowerShell on Windows agents. The editor offers these types:

• Registry paths accept the short hive names HKLM, HKCU, HKCR, HKU and HKCC, with or without a colon (HKLM:\…), as well as full names such as HKEY_LOCAL_MACHINE\….
• File paths allow wildcards (*) and environment variables such as %ProgramFiles%, so a single rule can match a versioned install folder.
• Every rule type except None needs its fields filled in. A File version is at least rule also needs a valid version number. If anything is missing, the save is refused and a message names the missing field.

Detection runs once per package per deployment#

Athena checks detection once, just before the package's first step, and remembers the answer for that package's remaining steps in the same deployment. This matters for multi-step installers. If step 1 installs the software, step 2 still runs, because the decision was made before step 1. A step's own condition script, if it has one, is still checked as well; the step runs only when both allow it.

Re-deploying an installed package#

A package's detection rule also applies when you deploy that package itself. If the rule says it is already installed on a machine, its steps are skipped there and the result reads Skipped: already installed. That way a rollout doesn't re-run a silent installer over an existing install, which can hang until the step times out. A package with no detection rule always runs.

To run the steps anyway, tick Force reinstall (run even if already installed) when you deploy. The option is on the package's deploy page and in the deploy dialog on the Deployments page. Force reinstall applies only to the package you are deploying. Its dependencies still follow their own Run setting. The choice is saved with the deployment, so a scheduled deployment honours it when it starts.

Depends on#

Each entry in Depends on is deployed before the package's own steps, in list order. Each entry has three settings:

A pin is a safety check, not a rollback. Athena keeps only the current contents of each package, so pinning 3.14.0 stops a deployment if the child has since been relabelled. It can't deploy an older copy.

The Deploy package step#

To run another package in the middle of a package's steps, add a step of type Deploy Package (REST stepType 13). At that position, the chosen package's steps run in place of the step, then the next step continues. For example, install the tool → deploy the plugin package → configure the tool. The step editor shows Package to deploy *, Version (Latest or a pinned label) and Run (Only if missing / Always). The step's Continue on Error checkbox works like Continue on failure.

Use Depends on for prerequisites that must be in place first. Use a Deploy package step when the child belongs at a specific point in the sequence.

How the tree is combined#

Save-time checks#

Athena checks the tree when you save the package and again when you deploy it, because a package edited later can break a tree that was valid when it was saved. A failed check refuses the save or deployment with a message:

Over REST, these are HTTP 400 responses with the message in the standard response envelope.

Permissions#

• Creating, editing and deleting packages requires packages.manage. Viewing a package, its plan, and its Used by list requires packages.view. Deploying requires packages.execute. See Permission Model.
• A saved dependency is deployed every time the parent is deployed. So when a save adds a dependency or a Deploy package step, the user saving it must also hold a deploy permission (deployments.execute or packages.execute). If an added child has a step that runs as a stored credential, the user also needs credentials.use. Re-saving a package without adding children doesn't require these. Otherwise the save is refused with HTTP 403.

Deleting a package that others use#

You can't delete a package while another package uses it as a dependency or through a Deploy package step. In the console, a toast names the dependents. Over REST, DELETE api/deployment-packages/{id} returns HTTP 409 with a message like 'Python 3.14' cannot be deleted: it is used by 'PyCharm Community'. Remove it from those packages first., and the dependents are listed in data.

Agent requirements#

Some agents can't run a package tree or detection rule. Athena refuses those agents when the deployment starts, and their result shows the reason. Other targets in the same deployment continue as normal.

Reading results: the package tree#

For a deployment that uses dependencies or detection, Active Deployments and Deployment History show a Package tree. The tree shows the deployed package with its children nested in run order. Each node shows a status per agent, and Show logs expands the step output for that node.

Agents don't send a separate report for a step they skip. Athena works out which steps were skipped from the order of the steps that were reported. In step results, a skipped step shows Condition not met: already installed (detection said installed) or Condition not met (its own condition was false). A step the agent never reached shows Not run: an earlier step failed. Over REST, GET api/deployment-packages/executions/{executionId} returns the same tree as resultTree, with nested children and per-agent agentResults.

REST API#

Enumerations are sent as numbers. A minimal update body that adds Python as a dependency, run only if missing:

{
  "name": "PyCharm Community",
  "folderName": "pycharm",
  "detectionType": 3,
  "detectionPath": "%ProgramFiles%\\JetBrains\\PyCharm Community*\\bin\\pycharm64.exe",
  "dependencies": [
    { "dependsOnPackageId": "<python-package-id>", "pinnedVersion": null, "runCondition": 0, "continueOnFailure": false }
  ],
  "steps": [ /* the package's steps - an update replaces the whole list */ ]
}

PowerShell#

The Athena PowerShell module supports dependencies from version 2.13.0:

# Python 3.14: detected by its registry key
$pyStep = New-AthenaDeploymentPackageStep -Name "Install Python" -StepType InstallApplication `
    -FileName python-3.14.0-amd64.exe -Arguments '/quiet InstallAllUsers=1 PrependPath=1' -SuccessExitCodes '0,3010'
$python = New-AthenaDeploymentPackage -Name "Python 3.14" -FolderName python-3.14 -Version 3.14.0 `
    -DetectionType RegistryKey -DetectionPath 'HKLM\SOFTWARE\Python\PythonCore\3.14\InstallPath' -Steps $pyStep

# PyCharm: depends on Python (installed first, only if missing)
$pcStep = New-AthenaDeploymentPackageStep -Name "Install PyCharm" -StepType InstallApplication `
    -FileName pycharm-community.exe -Arguments '/S'
$pycharm = New-AthenaDeploymentPackage -Name "PyCharm Community" -FolderName pycharm `
    -DetectionType FileExists -DetectionPath '%ProgramFiles%\JetBrains\PyCharm Community*\bin\pycharm64.exe' `
    -Steps $pcStep -Dependency (New-AthenaDeploymentPackageDependency -PackageId $python.Id)

# Preview what one deployment would run, and check for warnings
$plan = Get-AthenaDeploymentPackagePlan -Id $pycharm.Id
$plan.Nodes | Format-Table Key, ParentKey, PackageName, Version, Via, Gated
$plan.Warnings

Upload each package's installer file before deploying, as described in Files and rebuilding.