environments-and-servers.mdx

title	Managing Environments & Servers
description	Create environments, register servers, and manage agent tokens in Pullbase.

Environments and servers are the core records managed by the central server. This page covers lifecycle actions through the UI, CLI, and API.

Environments

Each environment links a Git repository to a Pullbase deployment target.

Create via web UI

Sign in and choose **Environments** from the sidebar. Provide a name (for example, `staging`) and optional description. - Repository URL: `https://github.com/your-org/configs.git` - Branch: `main` - Deploy path: `environments/staging/config.yaml` - Auto-reconcile: enabled by default Supply installation ID, repository ID, and app slug if the repo is private. After saving, the environment appears in the list. If webhooks are configured, Pullbase receives push events; otherwise it polls periodically.

Create via API

```bash cURL curl -X POST http://localhost:8080/api/v1/environments \ -H "Authorization: Bearer $ADMIN_TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "name": "staging", "description": "staging web tier", "repo_url": "https://github.com/your-org/configs.git", "branch": "main", "deploy_path": "environments/staging/config.yaml", "auto_reconcile": true }' ```

Servers

Servers represent managed nodes (VMs, bare-metal hosts, or containers) that run the Pullbase agent.

Register via API

curl -X POST http://localhost:8080/api/v1/servers \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "web-01",
    "name": "staging-web-01",
    "environment_id": 5
  }'

The response includes an agent token. Store it securely and set AGENT_TOKEN for the agent deployment.

List servers and status

curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:8080/api/v1/servers

Remove a server

```bash cURL curl -X DELETE http://localhost:8080/api/v1/servers/web-01 \ -H "Authorization: Bearer $ADMIN_TOKEN" ```

Deleting a server revokes its tokens and clears status history.

Agent tokens

Tokens authenticate agents; each server can have multiple active tokens for rotation.

Token management via CLI

• List: pullbasectl tokens list --server-url http://localhost:8080 --admin-token $ADMIN_JWT --server-id web-01
• Create: pullbasectl tokens create --server-url http://localhost:8080 --admin-token $ADMIN_JWT --server-id web-01 --description "blue-green" --expires-in 30
• Revoke: pullbasectl tokens revoke --server-url http://localhost:8080 --admin-token $ADMIN_JWT --server-id web-01 --token-id 17

Token fields

Field	Description
id	Token identifier used for revocation
description	Free-form label ("staging deployment", "ansible integration")
expires_at	Expiration timestamp (optional)
is_active	Indicates whether the token can be used
last_used_at	Last time the token was used for authentication

Automatic vs manual reconciliation

• Auto-reconcile enabled: Pullbase notifies agents of new commits. Agents reconcile on their next poll automatically.
• Auto-reconcile disabled: Pullbase records the new commit, but agents observe without applying changes until auto-reconcile is re-enabled.

Toggle auto-reconcile via the UI or API (POST /api/v1/environments/{id}/toggle-auto-reconcile).

Rollbacks

Rollback from the environment detail page or via POST /api/v1/environments/{id}/rollback:

```bash cURL curl -X POST http://localhost:8080/api/v1/environments/5/rollback \ -H "Authorization: Bearer $ADMIN_TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "to_commit": "8a9d3cba2f...", "reason": "Reverting faulty nginx config" }' ```

Pullbase creates a rollback event and updates the target commit. Agents reconcile to the specified commit on their next poll.

Webhook notifications

Pullbase can send HTTP notifications when drift is detected or apply errors occur. Configure webhooks per environment.

Configure via API

curl -X PUT http://localhost:8080/api/v1/environments/5 \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "notification_webhook_url": "https://hooks.slack.com/services/xxx/yyy/zzz"
  }'

Webhook payload

{
  "event": "drift_detected",
  "environment_id": 5,
  "environment_name": "staging",
  "server_id": "web-01",
  "commit_hash": "abc123...",
  "timestamp": "2026-01-01T12:00:00Z",
  "details": {
    "has_drift": true,
    "error_message": ""
  }
}

Event types:

• drift_detected: Agent detected configuration drift
• apply_error: Agent encountered an error applying configuration
• test: Sent when testing the webhook endpoint

Test webhook

Verify your webhook configuration before relying on it:

curl -X POST http://localhost:8080/api/v1/environments/5/test-webhook \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Retry behavior

Failed webhook deliveries are retried 3 times with exponential backoff (1s, 2s, 4s). If the server is shutting down or the request context is cancelled, retries stop early.

Use HTTPS endpoints for webhooks. Pullbase validates TLS certificates by default.

Best practices

• Use descriptive server_id values (for example, prod-api-01) to simplify searches.
• Rotate agent tokens regularly; maintain at least two active tokens during rotation to avoid downtime.
• Keep environment branches protected and enforce pull-request reviews.
• Tag production commits so rollbacks are easy to target.
• Configure webhook notifications for critical environments to get alerted on drift.

Store environment metadata (repo URL, branch, deploy path) in a configuration management repo to reproduce Pullbase configuration declaratively.