Skip to main content

Manifest Reference

The manifest file (autokitteh.yaml) is the configuration file that defines your AutoKitteh project. It specifies connections, triggers, variables, and other project settings.

File Structure​

version: v2

project:
  name: project_name

  connections:
    - name: connection_name
      integration: integration_type
      # Additional connection-specific configuration

  triggers:
    - name: trigger_name
      type: webhook | schedule
      event_type: event_type_name
      connection: connection_name
      call: file.py:function_name
      filter: CEL_expression

  vars:
    - name: VAR_NAME
      value: var_value

Top-Level Fields​

version​

Required. Specifies the manifest schema version.

Supported values:

  • v2 - Current recommended version (default)
  • v1 - Legacy version (deprecated)

Example:

version: v2

project​

Required. Contains all project configuration.

Project Fields​

name​

Required. The unique name of your project.

Type: String

Example:

project:
  name: my_workflow

connections​

Optional. List of connections to external services.

Each connection requires:

  • name - Unique identifier for this connection (used in code)
  • integration - One of the supported integrations
  • Additional fields depend on the integration type

Example:

connections:
  - name: my_slack
    integration: slack

  - name: my_github
    integration: github

See the integrations documentation for integration-specific configuration.

triggers​

Optional. List of triggers that start workflow sessions.

Each trigger can have:

FieldRequiredTypeDescription
nameYesStringUnique trigger identifier
typeNoStringwebhook or schedule
event_typeNoStringEvent type provided by the integration
connectionNo*StringConnection name (required for integration triggers)
callYesStringEntry point in format file.py:function_name
filterNoStringCEL expression to filter events
is_syncNoBooleanFor webhooks: return HTTP response from workflow

* connection is required for integration-based triggers but not for standalone webhooks.

Example - Webhook Trigger:

triggers:
  - name: http_endpoint
    type: webhook
    call: program.py:handle_webhook

Example - Integration Event Trigger:

triggers:
  - name: on_github_issue
    connection: my_github
    event_type: issues
    filter: data.action == 'opened'
    call: program.py:handle_issue

Example - Scheduled Trigger:

triggers:
  - name: daily_report
    type: schedule
    schedule: "0 9 * * *" # Daily at 9 AM
    call: program.py:generate_report

Example - Synchronous Webhook:

triggers:
  - name: api_endpoint
    type: webhook
    is_sync: true
    call: program.py:api_handler

vars​

Optional. List of environment variables available to your code.

Each variable requires:

  • name - Variable name (accessible via os.getenv())
  • value - Variable value

Example:

vars:
  - name: CHANNEL_ID
    value: "C12345678"

  - name: API_ENDPOINT
    value: "https://api.example.com"

Variables can also be set as secrets using the CLI:

ak var set --secret --env <env_id> TOKEN s3cr3t

See Working with Secrets for more information.

Filter Expressions​

Filters use CEL (Common Expression Language) to selectively trigger executions.

Event Type Filtering​

# Single event type
filter: event_type == 'issue_created'

# Multiple event types
filter: event_type == 'issue_created' || event_type == 'issue_updated'

# Pattern matching
filter: event_type.startsWith('issue_')
filter: event_type.endsWith('_created')
filter: event_type.contains('comment')

Data Filtering​

# Simple field check
filter: data.action == 'opened'

# Multiple conditions
filter: data.method == 'POST' && data.url.path.endsWith('/api')

# List membership
filter: data.method in ['GET', 'HEAD']

# Size checks
filter: size(data.items) > 5

# Nested fields
filter: data.issue.state == 'open'

See the CEL specification for complete syntax.

Complete Examples​

Simple HTTP Webhook​

version: v2

project:
  name: simple_webhook

  triggers:
    - name: incoming
      type: webhook
      call: program.py:on_request

GitHub Integration​

version: v1

project:
  name: github_notifier

  connections:
    - name: github_conn
      integration: github

  triggers:
    - name: on_pr
      connection: github_conn
      event_type: pull_request
      filter: data.action == 'opened'
      call: program.py:handle_pr

  vars:
    - name: SLACK_CHANNEL
      value: "#github-notifications"

Multi-Integration Project​

version: v1

project:
  name: workflow_automation

  connections:
    - name: slack_conn
      integration: slack

    - name: gmail_conn
      integration: gmail

    - name: sheets_conn
      integration: googlesheets

  triggers:
    - name: slack_command
      connection: slack_conn
      event_type: slash_commands
      call: program.py:handle_command

    - name: new_email
      connection: gmail_conn
      event_type: message_received
      filter: data.from.contains('@example.com')
      call: program.py:process_email

    - name: daily_sync
      type: schedule
      schedule: "0 0 * * *"
      call: program.py:daily_sync

  vars:
    - name: SPREADSHEET_ID
      value: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"

Best Practices​

  1. Use descriptive names for projects, connections, and triggers
  2. Leverage filters to reduce unnecessary session creation
  3. Keep secrets out of the manifest - use the CLI's secret management instead
  4. Use environment variables for values that change between deployments
  5. Document your triggers with clear, descriptive names

See Also​