Common characteristics

A task corresponds to a process that can be executed.

Tasks are grouped by project.

Several types of tasks can be created (shell or sql script, workflow, etc.), but they all share certain characteristics.

Scheduling

Each task can be scheduled using a cron expression that follows this format.

For example, to execute a task at 3 AM every 8th and 13th day of the month, you simply need to use this expression:

0 3 8,23 * *

Notifications

If notifiers (Slack, Microsoft Teams, email, etc.) have been configured for your project, you can assign one to your task to send a notification:

  • When execution starts
  • When execution ends ( = fails, is aborted, or completes successfully)
  • When execution fails or is aborted

Execution triggering

Task executions can be triggered by:

  • Admin users or Users attached to the task’s project (via the webapp or REST API)
  • Ctfreak’s internal scheduler (every monday at 2pm, …)
  • Incoming webhooks (push to a branch in a github/gitlab repo, event in a home automation server, alert received from third-party software, …)
  • A workflow task

Multiple execution policy

When receiving an execution request while an execution is already running for a given task, several scenarios are possible.

Reject

One execution at a time is allowed, so any new execution request will be rejected until the current execution is finished.

Smart chaining

A new execution is created with a pending status and will only start when the current one is finished.

Any new execution request will be rejected as long as an execution with a pending status already exists.

This execution policy is recommended for setting up a CI/CD pipeline (for example, a build task triggered by an incoming webhook following a push on a Github/Gitlab repository).

Replacement

The current execution receives an aborting request.

A new execution is created with a pending status and will only start when the current one is completely aborted.

Any new execution request will be rejected as long as an execution with a pending status already exists.

Concurrency

A new execution is created and started concurrently with the current one.

Make sure that your task is designed to support concurrent executions before using this execution policy.

Incoming Webhooks

Incoming webhooks allow for the execution of a task without going through the authentication process.

It’s the perfect way to trigger the execution of tasks by third-party software (for example, trigger a compilation script after a push to a branch in a git repository).

Creation

To add a webhook, go to Projects -> Select a task -> Incoming webhooks -> New webhook -> Select a webhook type and complete the form.

After validating the creation form, the URL for calling your webhook is available.

Webhook and task

An incoming webhook is attached to a single task, and it is possible to set up multiple incoming webhooks to execute a task.

Webhook call

Calling a webhook always involves an HTTP POST request with an empty payload or a JSON format payload.

We receive a JSON in the following format in return:

{
  "status": <HTTP status code>,
  "executionId": "<Execution ID that was just created, or null in case of failure>",
  "message": "<Status or error message>"
}

Execution condition

When the execution condition field is filled in, the payload (in JSON format) must satisfy this condition (in JMESPATH format) for the task associated with the webhook to be executed.

For example, with this received payload:

{
   "pusher":{
      "email":"bob@ctfreak.com",
      "name":"Bob"
   },
   "ref":"refs/heads/master"
}

and this execution condition:

(ref == 'refs/heads/master' && pusher.name == 'Alfred')

The associated task will not execute because the pusher.name does not match.

Note: When the execution condition is not satisfied, Ctfreak still returns an HTTP status code 200.

Webhook types

Generic webhook

This type of webhook only includes the common characteristics of webhooks.

For example, it can be called with a simple curl request:

curl --request POST --url http://localhost:6700/wh/MudO63QwyeoI5bpQ0FXgZjb6Kxtizg1U6y5pphgpJnme5OhBPW4GBLjmZZhT

And in return, receive the ID of the execution that was just created.

{
  "status": 200,
  "executionId": "01GSNB2678YM5DZS6X2FZPZAJY",
  "message": "I got the payload!"
}

Github webhook

You can specify a secret token to validate received payloads.

Note: A signature is sent with the hook request in the X-Hub-Signature-256 header. To verify that the request is legitimate, Ctfreak will calculate a hash using the secret token and ensure that the result matches the signature.

When a new webhook is setup in GitHub a ping event is sent to confirm the webhook. Ctfreak will receive the ping event and return a success response, but will not run the related task.

When creating a github webhook, the default execution condition restricts execution to pushes on the master branch:

ref == 'refs/heads/master'

Feel free to customize it according to your needs.

Gitlab webhook

You can specify a secret token to validate received payloads.

Note: The token is sent with the hook request in the X-Gitlab-Token HTTP header. Ctfreak will check the token to verify that the request is legitimate.

When creating a gitlab webhook, the default execution condition restricts execution to pushes on the master branch:

ref == 'refs/heads/master'

Feel free to customize it according to your needs.