Skip to main content
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

1

Open Environments

Sign in and choose Environments from the sidebar.
2

Click New Environment

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

Configure Git

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

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

FieldDescription
idToken identifier used for revocation
descriptionFree-form label (“staging deployment”, “ansible integration”)
expires_atExpiration timestamp (optional)
is_activeIndicates whether the token can be used
last_used_atLast 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.