Cerberus - The Gatekeeper to your Branches

What is it

Cerberus is designed to be run as a small HTTP service (typically as a Lambda in AWS) and will monitor HTTP post requests to block or unblock Git branches in GitLab.

Building

Using the supplied Makefile you can build a new binary of Cerberus:

> make build

This will output a new version of Cerberus in bin/cerberus

Deploying

Using the supplied Makefile you can package and deploy a new verion of Cerberus to AWS Lambda. It requires the following to be setup on your machine:

• AWS CLI v2+ (brew install awscli)

• a valid AWS configuration with access to the stackstate-tooling profile.

> make package deploy

This will upload Cerberus to an AWS S3 bucket, and then deploy it as an AWS Lambda using CloudFormation

Blocking a branch

Using a simple REST call it is possible to block a branch. The format for such a call would be:

POST https://url-of-your-lambda.amazonaws.com HTTP/1.1
Content-Type: application/json

{
    "action": "block",
    "context": {
        "project.id": "{{project-id}}",
        "project.slug": "stackvista/stackstate",
        "project.name": "StackState",
        "branch": "master",
        "pipeline": "207583705",
        "commit.sha": "ab3498ads4r98",
        "commit.title": "Merge of STAC-0-foo"
    }
}

Manually calling unblock

If the Slack integration is broken, it is possible to manually issue a REST request to Cerberus to unblock the wanted branch. The format for such a call is:

POST https://url-of-your-lambda.amazonaws.com HTTP/1.1
Content-Type: application/json

{
    "action": "unblock",
    "context": {
        "project.id": "{{project-id}}",
        "branch": "master"
    }
}

FAQ

How to manually unblock a branch

You can also manually unblock a branch by calling the GitLab REST API directly, or going to the GitLab UI.

For a manual API call ensure you have a Personal Access Token. Then you can issue the following 2 requests:

DELETE https://gitlab.com/api/v4/projects/{{project-id}}/protected_branches/master HTTP/1.1
Content-Type: application/json
PRIVATE-TOKEN: {{token}}

###

POST https://gitlab.com/api/v4/projects/{{project-id}}/protected_branches HTTP/1.1
Content-Type: application/json
PRIVATE-TOKEN: {{token}}

{
    "id": {{project-id}},
    "name": "master",
    "allowed_to_merge": [{
        "access_level": 40
    }, {
        "user_id": 4378321
    }],
    "allowed_to_push": [{
        "access_level": 0
    }],
    "allowed_to_unprotect": [{
        "access_level": 40
    }]
}