Managing Environments & Servers

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

Open Environments

Click New Environment

Provide a name (for example, staging) and optional description.

Configure Git

Repository URL: https://github.com/your-org/configs.git
Branch: main
Deploy path: environments/staging/config.yaml
Auto-reconcile: enabled by default

Optional: GitHub App

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

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

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:

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.

Foundations

Setup

Operations

Examples

Environments

Create via web UI

Create via API

Servers

Register via API

List servers and status

Remove a server

Agent tokens

Token management via CLI

Token fields

Automatic vs manual reconciliation

Rollbacks

Webhook notifications

Configure via API

Webhook payload

Test webhook

Retry behavior

Best practices

​Environments

​Create via web UI

​Create via API

​Servers

​Register via API

​List servers and status

​Remove a server

​Agent tokens

​Token management via CLI

​Token fields

​Automatic vs manual reconciliation

​Rollbacks

​Webhook notifications

​Configure via API

​Webhook payload

​Test webhook

​Retry behavior

​Best practices

Environments

Create via web UI

Create via API

Servers

Register via API

List servers and status

Remove a server

Agent tokens

Token management via CLI

Token fields

Automatic vs manual reconciliation

Rollbacks

Webhook notifications

Configure via API

Webhook payload

Test webhook

Retry behavior

Best practices