Table of Contents

Build API

Table of Contents

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, ssh_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 ssh_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 ssh_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:

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

Example request (curl):

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:

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

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, ssh_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 ssh_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 ssh_key and sshPrivateKey is not set.

Example request (curl):

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:

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):

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

Successful response example:

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):

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

Successful response example:

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):

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

Successful response example:

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):

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

Successful response example:

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):

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

Successful response example:

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):

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

Successful response example:

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):

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:

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):

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

Successful response example:

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):

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:

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):

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

Successful response example:

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):

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

Successful response example:

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):

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

Successful response example:

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):

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

Successful response example:

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