Skip to main content
Pullbase reads your Git repository to determine the desired state for each environment. By convention you store a config.yaml file at the root of the environment directory.

​
Repository layout

configs/
├── environments/
│   ├── production/
│   │   └── config.yaml
│   └── staging/
│       └── config.yaml
├── shared/
│   ├── nginx.conf
│   └── scripts/
└── README.md
  • Keep environment-specific files under environments/<name>
  • Store shared templates or scripts outside the environment folder
  • Reference shared files from config.yaml using relative paths

​
config.yaml schema

The agent parses this file to reconcile packages, services, and files on the managed host.
config.yaml
serverMetadata:
  name: web-01
  environment: production

packages:
  - name: nginx
    state: latest
  - name: curl
    state: present
  - name: vim
    state: absent

services:
  - name: nginx
    enabled: true
    state: running
    managed: true

files:
  - path: /etc/nginx/nginx.conf
    content: |
      user nginx;
      worker_processes auto;
      events {
        worker_connections 1024;
      }
      http {
        include       /etc/nginx/mime.types;
        default_type  application/octet-stream;
        sendfile        on;
        keepalive_timeout  65;
        server {
          listen 80;
          location / {
            return 200 'Hello from Pullbase';
          }
        }
      }
    mode: "0644"
    reloadService: nginx

system:
  serviceManager: systemd
  containerized: false

​
Sections explained

​
serverMetadata

Optional metadata that appears in the UI and log entries.
FieldTypeDescription
namestringHuman-readable server name
environmentstringEnvironment identifier for logging

​
packages

Package manager operations. The agent auto-detects the package manager (APK, APT, YUM/DNF) based on the host OS.
FieldTypeValuesDescription
namestring-Package name
statestringpresent, latest, absentDesired package state
  • present: Install if missing
  • latest: Install or update to latest version
  • absent: Remove if installed

​
services

Service management using the detected or configured service manager.
FieldTypeDefaultDescription
namestring-Service name
enabledboolean-Start on boot
statestring-running or stopped
managedbooleantrueSet to false to observe without altering state

​
files

File content management with optional service reload triggers.
FieldTypeDescription
pathstringAbsolute path on the target system
contentstringFile content (inline)
sourcestringRelative path in the repo (alternative to content)
modestringFile permissions in octal (e.g., "0644")
reloadServicestringService to reload/restart when file changes
reloadCommandstringCustom command to run when file changes

​
system

Optional system configuration for the agent.
FieldTypeValuesDescription
serviceManagerstringsystemd, supervisor, openrcOverride auto-detected service manager
containerizedbooleantrue/falseIndicate if running in a container
Large files can be committed alongside config.yaml and referenced with the source attribute instead of inline content.

​
Example with source files

files:
  - path: /etc/nginx/nginx.conf
    source: ../shared/nginx.conf
    reloadService: nginx
Ensure the relative path exists in the repository. The agent copies the file to the target location during reconciliation.

​
Example with reload command

files:
  - path: /etc/myapp/config.json
    content: |
      {"debug": false, "port": 3000}
    mode: "0640"
    reloadCommand: systemctl reload myapp

​
Supported package managers

The agent auto-detects and supports:
Package ManagerDistribution
APKAlpine Linux
APTDebian, Ubuntu
YUMRHEL, CentOS 7
DNFRHEL 8+, Fedora, Rocky Linux

​
Supported service managers

The agent auto-detects and supports:
Service ManagerInit System
systemdMost modern Linux distributions
supervisorDocker containers, custom setups
OpenRCAlpine Linux, Gentoo
Override auto-detection using the system.serviceManager field when the agent runs in an environment where detection fails (e.g., containers without full init).

​
Secrets management

  • Avoid committing secrets to Git. Store them in your secret manager and inject them at runtime (for example, via environment variables or file mounts).
  • If you must reference credentials, use encrypted files and have the agent decrypt them in a post-processing step.
  • Configure package repositories to use system-level credentials (e.g., /etc/apt/auth.conf) rather than embedding tokens in config.yaml.

​
Branching strategy

  • Use one branch per promotion stage (for example, main → staging → production).
  • Add Pullbase environments pointing to the relevant branch and deploy path.
  • Protect branches with pull requests and CI validation to ensure the desired state compiles.

​
Testing configuration changes

  1. Update config.yaml and related files in a feature branch.
  2. Validate YAML syntax locally with a linter.
  3. Merge to the environment branch.
  4. Trigger a webhook or rely on polling to publish the new commit.
The agent includes built-in validation for YAML structure, but semantic checks (such as verifying package names) depend on the target OS. Test changes in staging before promoting to production environments.