Deployment Worker

A Deployment Worker checks out selected branches and runs operator-defined commands in long-lived preview slots for QA, demos, or staging. The component is optional when deployment slots are not used, but every deployment slot requires a connected worker.

Deployment slots execute repository code on the worker host. Run workers on dedicated, least-privilege machines and do not use a preview slot as a production deployment system.

Deployment commands and their child processes run under worker resource limits that reserve CPU capacity for worker control operations. Output, input, exit-code, timeout, cancellation, and process cleanup behavior remain unchanged.

Deployment model

The application stores workspace, slot, template, branch, variable, and repository settings. Each worker stores only its connection and storage configuration.

Object	Purpose
Host	Registered worker machine, approval state, availability, and optional workspace allowlist.
Deploy template	Reusable initial, startup, and shutdown commands for one workspace.
Slot	A named deployment on a host that selects a template and supplies per-slot values.

A host can serve only workspaces allowed by its host configuration. An empty workspace allowlist permits every workspace, so use explicit assignments on shared or less-trusted hosts.

Install a worker

Install the worker package as a Windows service by following Installation. Before starting it:

1. Create a Deploy host API key under Hosts → API Keys.
2. Restrict the key by source IP when the worker has a stable address.
3. Protect the key as a service credential; never commit it to a repository.
4. Grant the service account write access only to its storage path and the minimum rights required by deploy commands.
5. Permit outbound HTTPS to the Polygent server and required Git hosts.
6. Install every runtime used by templates, such as Bash, PowerShell, Node.js, or Python.

The worker reads appsettings.json beside the installed executable:

{
  "Agent": {
    "Name": "deploy-01",
    "ServerId": "deploy-01",
    "MainServerUrl": "https://polygent.example.com",
    "ApiKey": "<deploy-host-api-key>",
    "StoragePath": "C:\\Polygent\\deploy-worker-data",
    "DisableGitSslVerification": false
  }
}

Key	Requirement
Agent:Name	Recognizable display name shown on the Hosts page.
Agent:ServerId	Recommended. Stable identifier, unique across all deployment workers.
Agent:MainServerUrl	HTTPS base URL reachable from the worker.
Agent:ApiKey	Active Deploy-type host API key.
Agent:StoragePath	Dedicated local path with enough capacity for repository copies and build output.
Agent:DisableGitSslVerification	Optional managed Git certificate-verification opt-out; defaults to false.

Agent:ServerId is the worker's identity on the server. Because the server keys hosts on this value rather than on the worker's IP address, several workers that reach the server through one shared address — for example over a VPN or behind NAT — stay separate hosts on the Hosts page, each with its own slots, status, metrics, and deploy actions. Set it once per worker and keep it stable: reconnecting with the same value updates the existing host instead of creating a duplicate, even if the worker's address changes.

Give every worker a different ServerId. If you omit it, the worker still starts and the server identifies it by its IP address instead, logging a warning on both sides — fine when the worker has its own address, but two workers sharing one address then collide on a single host record and the second one to connect is rejected. A worker presenting a ServerId that another connected worker already claimed is likewise rejected, so one worker can never silently overwrite another.

When upgrading existing workers, set each ServerId to the IP address that worker previously registered with to keep its current host record and configured slots; leaving ServerId unset achieves the same result through the IP fallback. Note that adding an explicit ServerId to a worker that was running on the fallback registers it as a new host — move its slots over, then delete the old record.

Keep Agent:DisableGitSslVerification false or omit it whenever Git can validate the server certificate. Setting it to true disables verification for worker-managed clone, fetch, pull, push, remote validation, branch listing, and remote branch checks against new and existing checkouts. It does not affect Git commands authored in deployment templates and does not change browser or operating-system certificate stores. Disabling verification permits interception of repository content and credentials; use it only after explicitly accepting that risk for a known internal Git server. The worker emits a prominent startup warning without logging repository credentials.

Restrict read access to appsettings.json, back up the central application and database rather than worker checkouts, and exclude the worker storage path from interactive user access. Revoke and replace the API key when a host is retired or suspected compromised.

Create a deploy template

A deploy template defines the commands a workspace permits slots to execute.

1. Open Workspace → Deploy Templates and create a template.
2. Add commands to the required phases.
3. Select the repository working directory or Slot root for every command.
4. Mark commands that users may skip as Optional step, then choose whether each is Enabled by default.
5. Declare reusable variables and mark credentials or tokens Secret.
6. Mark values that must be supplied by every slot Required.
7. Preview the saved template and verify paths and redaction before assigning it to a slot.

Phase	When it runs
Initial Commands	Once on the slot's first deployment.
Startup Commands	On deploy and start; run sequentially or in parallel as configured.
Shutdown Commands	On stop and before replacement where shutdown is required.

Commands are mandatory unless Optional step is enabled. When starting a host, ticket, or session deployment, each optional command appears as a checkbox initialized from Enabled by default. The selection applies to Initial, Startup, and Shutdown actions throughout that deployment lifecycle. Redeploying presents the current template defaults again; it does not silently reuse the previous selection. Templates without optional commands show no optional-step section.

Commands support Bash, PowerShell, Command Prompt, Node.js, and Python. They run non-interactively under the worker service account. Use absolute tool paths where service-account PATH configuration is uncertain, fail with a non-zero exit code, and keep commands safe to retry.

Variables and built-in tokens

Variables let one template serve multiple slots without embedding environment-specific values.

Token	Value
{WorkspaceId}	Workspace identifier.
{SlotName}	Slot name.
{WorkingDirectory}	Selected repository directory or slot root.
{SlotRoot}	Root directory containing all repositories for the slot.
{RepositoryFolder}	Selected repository folder; empty for slot-root commands.
{StoragePath}	Worker storage path.
{GitBranch}	Deployed branch.
{StarterBranch}	Base branch when supplied by the deployment source.

Secret values are protected at rest and redacted from normal status and error output, but the launched process receives the clear value. Do not print secrets, pass them on a command line when an environment variable is supported, or allow untrusted users to edit deploy commands.

Watch directories

Watch directories skip a command when its declared input directories have not changed since the same command last succeeded.

Paths are relative to the command's working directory and respect repository ignore rules. Leave the setting empty for commands that must always run. Do not use watched-input skipping for database migrations, service registration, security checks, or other required side effects.

Configure and operate a slot

A slot binds a host, workspace, template, and environment-specific values.

1. Create the slot and select an approved online host.
2. Select a deploy template and set all required variable overrides.
3. Set the public or internal URL displayed to users; this is informational and does not configure DNS, TLS, a reverse proxy, or a firewall.
4. Deploy a session branch or a compatible set of ticket branches.
5. Review command output and verify the URL before handing the slot to QA.
6. Use Stop to run shutdown commands without deleting the checkout; use Start to run startup commands again.

For multi-repository workspaces, every repository needs an explicit deployable branch. Ticket deployments can combine compatible ticket branches in a slot; resolve branch conflicts before relying on the environment.

Security and permissions

Deployment access combines role permissions, workspace membership, host restrictions, and host credentials.

Permission	Capability
View Hosts	View host and slot state.
Manage Hosts	Create and manage hosts and slots and run deployment actions. Workspace configuration access is also required to edit deploy templates.
Manage Host API Keys	Create, rotate, revoke, and restrict worker credentials.

Keep API-key management separate from routine slot operation. Review key-expiry and authentication-failure notifications, remove obsolete host approvals, and patch worker hosts and installed runtimes regularly.

Deploy templates are privileged code execution. Restrict template editing to trusted operators, review changes, use a non-administrator service account, isolate workers from sensitive networks, and scope repository credentials to only the repositories and operations required.

Upgrade and recovery

The worker and server must run compatible releases.

1. Stop active slots or schedule an interruption.
2. Back up worker configuration and any external state created outside the worker storage path.
3. Stop the Windows service, replace the installed worker package, and retain the Agent configuration.
4. Start the service and confirm the host is online before redeploying slots.

Older worker configurations that contain local workspace or slot definitions are no longer used. Recreate those templates and slots in the UI, then remove obsolete local configuration after verification.

Troubleshooting

Use the Hosts page, slot command output, Windows Service Control Manager, and worker/server logs together.

Symptom	Resolution
Host remains offline	Verify the service is running, server URL and TLS trust are correct, outbound connectivity works, and the API key is active and of Deploy type.
Registration is rejected	Approve the host if required, check the key's IP allowlist, and confirm the license has available deploy-host capacity.
Slot cannot use a host	Check the host's workspace allowlist and the user's workspace membership and host permissions.
Repository checkout fails	Verify the workspace repository URL, Git credential, branch, DNS/TLS access, and disk space.
Required variable error	Supply a non-empty template default or slot override, then retry. Stop remains available for cleanup.
Runtime is not found	Install the selected runtime for the service account or use its absolute executable path.
Command works interactively but fails as a service	Compare service-account permissions, PATH, working directory, environment variables, and network/proxy access.
Slot fails on initial commands	Select Show details to review the full output, then run the commands manually on the host to reproduce the failure.
Slot details report that the log is unavailable	Confirm the host is online and check whether a newer deployment replaced the log.
Batch deployment reports skipped tickets	Resolve every reported repository failure; each ticket needs a branch in every required repository.
URL is unreachable after success	Configure DNS, TLS, reverse proxy, application binding, and firewall rules separately; the slot URL does not create them.
Disk usage grows	Stop unused processes, delete obsolete slots through the UI, and size or monitor the configured storage volume. Do not manually delete an active slot directory.
Secret appears in output	Rotate it immediately, remove the disclosure, and change the command so it does not print or expose the value.