The Build API enables you to easily manage policy projects and their respective CFEngine Build modules.

Projects API

A project is a set of CFEngine Build modules and custom files/json/policy files.

Create project

URI: https://hub.cfengine.com/api/build/projects

Method: POST

Parameters:

  • repositoryUrl (string) Git repository URL. Project will be synchronized with this repository. Supported protocols: http, https, ssh , git. Required. Git repository URL example: https://github.com/username/repository.git

  • branch (string) Repository branch. Required.

  • name (string) Project name. Required.

  • authenticationType (string) Authentication type that will be used to get access to the repository. Allowed values: password, private_key. Required.

  • username (string) Username for authentication to the repository. Required when authentication type is password.

  • password (string) Password for authentication to the repository. Required when authentication type is password.

  • sshPrivateKey (string) SSH private key for authentication to the repository. Required when authentication type is private_key and sshKeyId is not set.

  • sshKeyId (integer) Generated SSH private key ID by SSH keys API for authentication to the repository. Required when authentication type is private_key and sshPrivateKey is not set.

Note: the SSH key is expected to be in openssh(rfc4716) format as generated by SSH Keys API or a command line like:

code
ssh-keygen -t rsa-sha2-512 -b 4096 -f test -m rfc4716

Example request (curl):

code
curl --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/build/projects \
  -H 'content-type: application/json' \
  -d '
  {
  "repositoryUrl": "https://github.com/username/repository.git",
  "branch": "master",
  "authenticationType": "password",
  "password" : "git_token_or_password",
  "username" : "git_username",
  "name": "Production"
  }'

Successful response example:

code
HTTP 200 Ok
{
    "id": "8"
}

Responses:

HTTP response code Description
200 OK Project successfully created
422 Unprocessable entity Validation error occurred
500 Internal server error Internal server error

Create local project

You can create a local project without repository data and the project will exist only locally. This type of project is useful for testing purposes.

URI: https://hub.cfengine.com/api/build/projects/local

Method: POST

Example request (curl):

code
curl --user <username>:<password> -X POST https://hub.cfengine.com/api/build/projects/local

Successful response example:

code
HTTP 200 Ok
{
    "id": "1"
}

Responses:

HTTP response code Description
200 OK Project successfully created
500 Internal server error Internal server error

Update project

By changing the repository url or branch you will initialize a new project and the current one will be removed from the file system and any un-pushed/un-deployed(terminology in Mission Portal UI) changes will be lost.

URI: https://hub.cfengine.com/api/build/projects/:id

Method: PATCH

Parameters:

  • id (integer) Project's ID. Required.

  • repositoryUrl (string) Git repository URL. Project will be synchronized with this repository. Supported protocols: http, https, ssh , git. Required. Git repository URL example: https://github.com/username/repository.git

  • branch (string) Repository branch.

  • name (string) Project name.

  • authenticationType (string) Authentication type that will be used to get access to the repository. Allowed values: password, private_key.

  • username (string) Username for authentication to the repository. Required when authentication type is password.

  • password (string) Password for authentication to the repository. Required when authentication type is password.

  • sshPrivateKey (string) SSH private key for authentication to the repository. Required when authentication type is private_key and sshKeyId is not set.

  • sshKeyId (integer) Generated SSH private key ID by SSH keys API for authentication to the repository. Required when authentication type is private_key and sshPrivateKey is not set.

Example request (curl):

code
curl --user <username>:<password> \
  -X PATCH \
  https://hub.cfengine.com/api/build/projects/2 \
  -H 'content-type: application/json' \
  -d '
  {
  "branch": "staging",
  }'

Successful response example:

code
HTTP 200 OK
{
    "id": "4"
}

Responses:

HTTP response code Description
204 No content Project successfully updated
404 Not found Project not found
422 Unprocessable entity Validation error occurred
500 Internal server error Internal server error

Get project

URI: https://hub.cfengine.com/api/build/projects/:id

Method: GET

Parameters:

  • id (integer) Project's ID. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/build/projects/2

Successful response example:

code
HTTP 200 OK
{
    "id": 2,
    "repository_url": "https://github.com/username/repository.git",
    "branch": "master",
    "name": "Production",
    "authentication_type": "password",
    "username": "admin",
    "is_empty": false,
    "created_at": "2022-03-17 14:01:56.23852+00",
    "pushed_at": null,
    "ssh_key_id": null,
    "password": "set",
    "ssh_private_key": "not set"
}

Note: The API does not return password or ssh private key, but returns set or not set.

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Project not found
500 Internal server error Internal server error

Get projects list

URI: https://hub.cfengine.com/api/build/projects

Method: GET

Parameters:

  • skip (integer) Number of results to skip for the processed query. The Mission Portal uses this for pagination. Optional parameter.
  • limit (integer) Limit the number of results in the query. Optional parameter.

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/build/projects

Successful response example:

code
HTTP 200 OK
{
    "data": [
        {
            "id": 3,
            "repository_url": "https://github.com/build/modules.git",
            "branch": "master",
            "name": null,
            "authentication_type": "password",
            "username": "admin",
            "is_empty": false,
            "created_at": "2022-03-17 13:13:21.107899+00",
            "password": "set",
            "ssh_private_key": "not set"
        },
        {
            "id": 4,
            "repository_url": "https://github.com/build/modules.git",
            "branch": "production",
            "name": null,
            "authentication_type": "password",
            "username": "admin",
            "is_empty": false,
            "created_at": "2022-03-17 13:13:23.333539+00",
            "password": "set",
            "ssh_private_key": "not set"
        }
    ],
    "meta": {
        "count": 2,
        "page": 1,
        "timestamp": 1647596804,
        "total": 2
    }
}

Note: The API does not return password or ssh private key, but returns set or not set.

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Project not found
500 Internal server error Internal server error

Delete project

URI: https://hub.cfengine.com/api/build/projects/:id

Method: DELETE

Parameters:

  • id (integer) Project's ID. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X DELETE \
  https://hub.cfengine.com/api/build/projects/2

Successful response example:

code
HTTP 204 No content

Responses:

HTTP response code Description
204 No content Project successfully deleted
404 Not found Project not found
500 Internal server error Internal server error

Sync project

URI: https://hub.cfengine.com/build/projects/:id/sync

Method: POST

Parameters:

  • id (integer) Project's ID. Required.
  • action (string) Action. Allowed actions:
    • push - pushes local changes to the upstream repository
    • rebase - rebases local changes from the upstream
    • force-pull - overwrites local project files from upstream repository
    • force-rebase - force rebases local changes from the upstream

Example request (curl):

code
curl --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/build/projects/2 \
  -d '
  {
  "action": "push",
  }'

Successful response example:

code
HTTP 204 No content

Responses:

HTTP response code Description
204 No content Project successfully synced
404 Not found Project not found
500 Internal server error Internal server error

Refresh project

Fetch upstream repository and return the current state.

URI: https://hub.cfengine.com/build/projects/:id/refresh

Method: POST

Parameters:

  • id (integer) Project's ID. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/build/projects/2/refresh

Successful response example:

code
HTTP 200 OK
{
    "status": "ahead",
    "details": [
        "Refreshed repository for project 4 with 'git fetch'"
    ]
}

Output:

  • status Project's status. Possible values:
    • ok - project is up-to-date
    • behind - there are changes in upstream which are not pulled
    • ahead - there are changes in the local project which are not pushed
    • diverged - there are changes which are not pushed and not pulled at the same time

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Project not found
500 Internal server error Internal server error

List of CFEngine Build modules added to project

URI: https://hub.cfengine.com/api/build/projects/:id/modules

Method: GET

Parameters:

  • id (integer) Project's ID. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/build/projects/5/modules

Successful response example:

code
HTTP 200 OK
[
    {
        "name": "masterfiles",
        "description": "Official CFEngine Masterfiles Policy Framework (MPF)",
        "tags": [
            "supported",
            "base"
        ],
        "repo": "https://github.com/cfengine/masterfiles",
        "by": "https://github.com/cfengine",
        "version": "3.18.1-1",
        "commit": "b6e9eacc65c797f4c2b4a59056293636c320d0c9",
        "added_by": "cfbs add",
        "steps": [
            "run ./prepare.sh -y",
            "copy ./ ./"
        ],
        "subdirectory": "",
        "isExternal": false,
        "availableVersion": "3.18.2"
    },
    {
        "name": "autorun",
        "version": "1.0.1",
        "description": "Enable autorun functionality",
        "tags": [
            "supported",
            "management"
        ],
        "repo": "https://github.com/cfengine/modules",
        "by": "https://github.com/olehermanse",
        "commit": "c3b7329b240cf7ad062a0a64ee8b607af2cb912a",
        "subdirectory": "management/autorun",
        "added_by": "cfbs add",
        "steps": [
            "json def.json def.json"
        ],
        "isExternal": false,
        "availableVersion": "1.0.1"
    }
]

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Project not found
500 Internal server error Internal server error

Add CFEngine Build module to project

URI: https://hub.cfengine.com/api/build/projects/:id/modules/:module

Method: POST

Parameters:

  • id (integer) Project's ID. Required.
  • module (string) Module's name. Required.
  • version (string) Module's version. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/build/projects/1/modules/autorun \
  -H 'content-type: application/json' \
  -d '
  {
  "version": "1.0.1"
  }'

Successful response example:

code
HTTP 201 Created

Responses:

HTTP response code Description
201 Created Module successfully added
404 Not found Project not found
422 Unprocessable entity Validation error occurred
500 Internal server error Internal server error

Delete CFEngine Build module from project

URI: https://hub.cfengine.com/api/build/projects/:id/modules/:module

Method: DELETE

Parameters:

  • id (integer) Project's ID. Required.
  • module (string) Module's name. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X DELETE \
  https://hub.cfengine.com/api/build/projects/1/modules/autorun

Successful response example:

code
HTTP 204 No content

Responses:

HTTP response code Description
204 No content Module successfully deleted from project
404 Not found Project not found
500 Internal server error Internal server error

Update CFEngine Build module version

URI: https://hub.cfengine.com/api/build/projects/:id/modules/:module

Method: PATCH

Parameters:

  • id (integer) Project's ID. Required.
  • module (string) Module's name. Required.
  • version (string) Module's version. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X PATCH \
  https://hub.cfengine.com/api/build/projects/1/modules/autorun \
  -H 'content-type: application/json' \
  -d '
  {
  "version": "1.0.2"
  }'

Successful response example:

code
HTTP No content

Responses:

HTTP response code Description
204 No content Module successfully updated
404 Not found Project not found
422 Unprocessable entity Validation error occurred
500 Internal server error Internal server error

Get list of available CFEngine Build modules

URI: https://hub.cfengine.com/api/build/modules

Method: GET

Parameters:

  • sortColumn (string) Column name on which to sort results. Default value: name. Optional parameter.
  • sortDescending (boolean) Sorting order. Optional parameter. Default value: false. Optional parameter.
  • searchQuery (string) Search query for a full-text search based on modules name and description. Optional parameter.
  • tag (string) Filter modules by tag. Optional parameter.
  • skip (integer) Number of results to skip for the processed query. The Mission Portal uses this for pagination. Optional parameter.
  • limit (integer) Limit the number of results in the query. Optional parameter.

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/build/modules/?searchQuery=autorun

Successful response example:

code
HTTP 200 OK
{
    "data": [
        {
            "name": "autorun",
            "readme": "<h1 id=\"enable-autorun\">Enable autorun</h1>\n<p>Simple module to enable autorun functionality, using def.json.</p>\n",
            "description": "Enable autorun functionality",
            "version": "1.0.1",
            "author": {
                "url": "https://github.com/olehermanse",
                "name": "Ole Herman Schumacher Elgesem",
                "image": "https://avatars.githubusercontent.com/u/4048546?v=4"
            },
            "updated": "2021-11-03 00:00:00+00",
            "downloads": 1837,
            "repo": "https://github.com/cfengine/modules",
            "documentation": null,
            "website": null,
            "subdirectory": "management/autorun",
            "commit": "c3b7329b240cf7ad062a0a64ee8b607af2cb912a",
            "dependencies": "[]",
            "tags": "[\"supported\", \"management\"]",
            "versions": {
                "1.0.0": {
                    "date": "Oct 26, 2021",
                    "latest": false
                },
                "1.0.1": {
                    "date": "Nov 1, 2021",
                    "latest": true
                }
            },
            "latest": true,
            "ts_vector": "'autorun':1A,3B 'enable':2B 'functionality':4B"
        }
    ],
    "meta": {
        "count": 1,
        "page": 1,
        "timestamp": 1657097484,
        "total": 1
    }
}

Responses:

HTTP response code Description
200 Ok Successful response
500 Internal server error Internal server error

Update list of available CFEngine Build modules

Modules will be received from the official CFEngine Build modules catalogue https://build.cfengine.com

URI: https://hub.cfengine.com/api/build/modules

Method: POST

Example request (curl):

code
curl --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/build/modules

Successful response example:

code
204 No content

Responses:

HTTP response code Description
204 No content Modules list successfully updated
500 Internal server error Internal server error

Get CFEngine build module by name

URI: https://hub.cfengine.com/api/build/modules/:name

Method: GET

Parameters:

  • name (string) Module name. Default value: name. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/build/modules/autorun

Successful response example:

code
HTTP 200 OK
{
    "name": "autorun",
    "readme": "<h1 id=\"enable-autorun\">Enable autorun</h1>\n<p>Simple module to enable autorun functionality, using def.json.</p>\n",
    "description": "Enable autorun functionality",
    "version": "1.0.1",
    "author": {
        "url": "https://github.com/olehermanse",
        "name": "Ole Herman Schumacher Elgesem",
        "image": "https://avatars.githubusercontent.com/u/4048546?v=4"
    },
    "updated": "2021-11-03 00:00:00+00",
    "downloads": 1837,
    "repo": "https://github.com/cfengine/modules",
    "documentation": null,
    "website": null,
    "subdirectory": "management/autorun",
    "commit": "c3b7329b240cf7ad062a0a64ee8b607af2cb912a",
    "dependencies": "[]",
    "tags": "[\"supported\", \"management\"]",
    "versions": {
        "1.0.0": {
            "date": "Oct 26, 2021",
            "latest": false
        },
        "1.0.1": {
            "date": "Nov 1, 2021",
            "latest": true
        }
    },
    "latest": true
}

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Module not found
500 Internal server error Internal server error

Get specific version of a CFEngine Build module by name

URI: https://hub.cfengine.com/api/build/modules/:name/:version/

Method: GET

Parameters: sortColumn searchQuery tag

  • name (string) Module name. Required.
  • version (string) Module version. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/build/modules/autorun/1.0.0/

Successful response example:

code
HTTP 200 OK
{
    "name": "autorun",
    "readme": "<h1 id=\"enable-autorun\">Enable autorun</h1>\n<p>Simple module to enable autorun functionality, using def.json.</p>\n",
    "description": "Enable autorun functionality",
    "version": "1.0.0",
    "author": {
        "url": "https://github.com/olehermanse",
        "name": "Ole Herman Schumacher Elgesem",
        "image": "https://avatars.githubusercontent.com/u/4048546?v=4"
    },
    "updated": "2021-11-03 00:00:00+00",
    "downloads": 1837,
    "repo": "https://github.com/cfengine/modules",
    "documentation": null,
    "website": null,
    "subdirectory": "management/autorun",
    "commit": "be3bc015f6a19e945bb7a9fa0ed78c97e2cecf61",
    "dependencies": "[]",
    "tags": "[\"supported\", \"management\"]",
    "versions": {
        "1.0.0": {
            "date": "Oct 26, 2021",
            "latest": false
        },
        "1.0.1": {
            "date": "Nov 1, 2021",
            "latest": true
        }
    },
    "latest": false
}

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Module not found
500 Internal server error Internal server error

Get CFEngine Build module input data

URI: https://hub.cfengine.com/api/build/projects/:id/modules/:name/input

Method: GET

Parameters:

  • id (integer) Project's ID. Required.
  • name (string) Module name. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/build/projects/1/modules/delete-files/input

Successful response example:

code
HTTP 200 OK
{
    "status": "ok",
    "input_spec": [
        {
            "type": "list",
            "label": "Files",
            "while": "Specify another file you want deleted on your hosts?",
            "bundle": "delete_files",
            "subtype": [
                {
                    "key": "path",
                    "type": "string",
                    "label": "Path",
                    "question": "Path to file"
                },
                {
                    "key": "why",
                    "type": "string",
                    "label": "Why",
                    "default": "Unknown",
                    "question": "Why should this file be deleted?"
                }
            ],
            "response": [
                {
                    "path": "/tmp/test",
                    "why": "no tests, please"
                }
            ],
            "variable": "files",
            "namespace": "delete_files"
        }
    ]
}

Output:

  • input_spec (JSON array of objects) Input specification represented as an JSON array of objects. Each object specifies one input entry for the module. To discover more information about these fields, please read Modules with input document.

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Project or module not found
500 Internal server error Internal server error

Set CFEngine Build module input data

URI: https://hub.cfengine.com/api/build/projects/:id/modules/:name/input

Method: POST

Parameters:

  • id (integer) Project's ID. Required.
  • name (string) Module name. Required.

Request body:

Request body should contain input specification from the Get input data request where each object should have a response property with the data.

response might be: * an JSON array of objects, in case of list input type with string subtypes. An object should be a key-value pair where a key is from input specification and value should be a string. * string, in case of string input type

Example request (curl):

code
curl --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/build/projects/1/modules/delete-files/input \
  --header 'Content-Type: application/json' \
  --data-raw '[
   {
      "type":"list",
      "label":"Files",
      "while":"Specify another file you want deleted on your hosts?",
      "bundle":"delete_files",
      "subtype":[
         {
            "key":"path",
            "type":"string",
            "label":"Path",
            "question":"Path to file"
         },
         {
            "key":"why",
            "type":"string",
            "label":"Why",
            "default":"Unknown",
            "question":"Why should this file be deleted?"
         }
      ],
      "variable":"files",
      "namespace":"delete_files",
      "response":[
         {
            "path":"/etc/test",
            "why":"no tests, please"
         }
      ]
   }
]'

Successful response example:

code
HTTP 200 OK
{
    "status": "ok"
}

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Project or module not found
500 Internal server error Internal server error