API Trigger

You can trigger a particular workflow using the following API call. You can either trigger an existing workflow that already contains other triggers or a new trigger using this method. If you want to trigger a new workflow, create a config file without the triggers field.

It supports both:

  • Existing GitHub-based workflows

  • Custom workflows passed inline (base64-encoded YAML)

Path

POST https://<org subdomain>.neetoci.com/api/v1/trigger_ci_job

Replace <org-subdomain> with your organization's subdomain.

Headers

Request Body Options

Option 1: Trigger an existing GitHub-based workflow

  • Required Fields

    • branch_name: Name of the branch to run the job on

    • project_name: Name of the project in neetoCI

    • workflow_name: Name of the workflow file

    • trigger_source: Must be "github"

  • Example

    {
      "branch_name": "add-api-trigger-workflow",
      "project_name": "wheel",
      "workflow_name": "default",
      "trigger_source": "github"
    }

Option 2: Trigger a CI job without GitHub (Inline Config)


You can bypass GitHub by passing the entire workflow YAML as a base64-encoded string.

  • Required Fields

    • base64_encoded_workflow_yaml: Base64 string of the workflow YAML

    • project_name: Name of the project (auto-created if missing)

    • workflow_name: Name of the workflow

    • trigger_source: Must be "generic"

  • Example

    {
      "workflow_name": "default",
      "project_name": "wheel",
      "trigger_source": "generic",
      "base64_encoded_workflow_yaml": "ZmxvdzogCiAgLSBuYW1lOiBidWlsZAogICAgcnVuOiB5YXJuIGJ1aWxkCiAgICBlbnY6CiAgICAgIEZPTzogYmFy"
    }
  • Required Environment Variables (for generic triggers)

    • The workflow file must define the following environment variables in the envs:section if the⁣ trigger_sourceis⁣generic:

      Key

      Description

      GH_BRANCH

      Name of the Git branch being used

      GH_COMMIT_SHA

      Commit SHA being referenced

      GH_REPO_FULL_NAME

      Repository in owner/repo format

      GITHUB_ACCESS_TOKEN

      GitHub token for repository access

Creating a webhook

You can create a webhook that sends updated information on the CI job that was triggered every time the status of the CI job changes.

In order to create a webhook along with the trigger, simply pass the endpoint at which the webhook should send requests in the webhook_url parameter.

Example

{
  "branch_name": "add-api-trigger-workflow",
  "project_name": "wheel",
  "workflow_name": "default",
  "webhook_url": "https://example.com/path/to/endpoint"
}

The webhook requests will also contain the API Key header from the trigger request - X-Api-Key . You can use it to authenticate the webhook requests on your endpoint.

Sample Payload from Trigger endpoint and Webhook

{
    "ci_job": {
        "id": "d81e8f73-0881-450b-af0a-68414d2d90ed",
        "created_at": "2023-10-30T12:00:32.405Z",
        "status": "pending",
        "parallelism": 1,
        "url": "https://subdomain.neetoci.com/projects/wheel/jobs/d81e8f73-0881-450b-af0a-68414d2d90ed",
        "workflow": {
            "is_cypress": false,
            "name": "default",
            "plan": {
                "id": "1528a387-b4c0-4741-a2a2-87fce91f0bdc",
                "capacity": 5,
                "cpu": 0.5,
                "memory": 1.0,
                "name": "Basic",
                "price": 0.0,
                "slug": "basic",
                "created_at": "2023-07-14T02:56:48.079Z",
                "updated_at": "2023-07-14T02:56:48.079Z",
                "ephemeral_storage": 10.0
            }
        }
    }
}