Blocks whose promise types come from CFEngine Build modules. Adding one adds its module to the project; saving installs it with cfbs. The module runs with Python, so hosts need python3.

Git Checkout

Clones a git repository into a folder and keeps it at a branch, tag or commit.

Generates: a git promise.

Module: promise-type-git, added to the project with the block.

Settings

Setting Required Description
Folder Yes Where the repository is cloned, e.g. /srv/app. Needs git on the host.
Repository URL Yes E.g. https://github.com/cfengine/starter_pack. A private one needs credentials for root (gitcredentials).
Branch, tag or commit Yes E.g. main or master: the git module can’t follow the remote’s default branch unnamed.
Keep it updated Yes One of: Yes: pull new commits, No: clone once. Default: Yes: pull new commits.
Local changes Yes One of: Keep them, Discard them. Default: Keep them.
History depth No Empty: the full history. 1: the latest commit only. At least 1.

Example

The policy it generates, for example:

# Clone the app
git:
  "/srv/app"
    repository => "https://github.com/cfengine/starter_pack",
    version => "main",
    update => "true",
    force => "false";

HTTP Request

Sends an HTTP(S) request, e.g. to download a file or call an API.

Generates: an http promise.

Module: promise-type-http, added to the project with the block.

Settings

Setting Required Description
URL Yes Starting with https:// or http://.
Method Yes One of: GET, POST, PUT, DELETE, PATCH. Default: GET.
Save the response to No Empty: the response is dropped (an OK status keeps the promise). The request runs on every agent run: set How often, or a condition.
Headers No One per line, Name: value.
Body No Sent as is; @/some/path sends a file.
Server certificate Yes One of: Checked, Not checked (insecure). Default: Checked.

Example

The policy it generates, for example:

# Download the logo
http:
  "https://cfengine.com/images/cfengine-logo.svg"
    method => "GET",
    file => "/var/www/html/logo.svg",
    insecure => "false";

Run Ansible Playbook

Runs an Ansible playbook on the host (connection local by default).

Generates: an ansible promise.

Module: promise-type-ansible, added to the project with the block.

Settings

Setting Required Description
Playbook Yes Its absolute path on the host, e.g. /srv/ansible/site.yml. Needs Ansible on the host.
Inventory No The inventory file or host list, e.g. /srv/ansible/hosts. Empty: Ansible’s default inventory.
Tags No Only the plays and tasks with these tags, one per line.
Limit to hosts No Hosts or groups, one per line.
Become Yes One of: No, Yes (sudo). Default: No.
Become user No Empty: root.

Example

The policy it generates, for example:

# Run the site playbook
ansible:
  "/srv/ansible/site.yml"
    tags => { "web" },
    become => "false";

Systemd Unit

Keeps a systemd service running or stopped, and can write its unit file.

Generates: a systemd promise.

Module: promise-type-systemd, added to the project with the block.

Settings

Setting Required Description
Service name Yes E.g. myapp (myapp.service).
State Yes One of: Running, Stopped, Removed (with its unit file), Restarted on every run, Reloaded on every run. Default: Running.
Start on boot Yes One of: Yes, No. Default: Yes.
Reload systemd first Yes daemon-reload before acting, e.g. after a unit file changed outside this block. One of: Yes, No. Default: No.
Description No Setting any unit field below writes the unit file (/etc/systemd/system/.service).
Start commands No ExecStart, one per line, e.g. /usr/bin/myapp –port 8080.
Type No One of: Default (simple), simple, forking, oneshot, notify.
Run as user No The user the service runs as. Empty: root.
Restart No One of: Never, On failure, Always.
Start after No Units, one per line, e.g. network-online.target.

Example

The policy it generates, for example:

# Run my app
systemd:
  "myapp"
    state => "started",
    enabled => "true",
    daemon_reload => "false",
    unit_description => "My app",
    service_exec_start => { "/usr/bin/myapp --port 8080" },
    unit_after => { "network-online.target" };