> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kolaria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Event-Based Automation

> Trigger content generation when a GitHub release is published or code lands on the default branch

Event triggers generate content in response to GitHub activity: a published release, or a push to the repository's default branch. Each trigger listens on one or more repositories, fires for one event type, and produces one output format. You manage them under **Automation > Events** in the dashboard or through the `/v1/event-triggers` API.

## How event triggers work

<Steps>
  <Step title="GitHub event occurs">
    A release is published, or commits are pushed to the default branch.
  </Step>

  <Step title="Webhook received">
    GitHub sends the event to the repository's webhook URL in Kolaria.
  </Step>

  <Step title="Validation">
    Kolaria verifies the signature, drops duplicate deliveries, and checks that the repository is connected and enabled and that a matching trigger is enabled.
  </Step>

  <Step title="Content generation">
    The run reads the event and the hour of repository activity leading up to it, then writes the content in your brand identity.
  </Step>

  <Step title="Review">
    The result appears under **Content** as a draft, or as a published post when auto-publish is on.
  </Step>
</Steps>

## Supported event types

<Tabs>
  <Tab title="Release published">
    Fires when a release is published on GitHub. Draft releases are ignored.

    **GitHub actions that fire it:**

    * `published`
    * `prereleased`

    **Include pre-releases:** each release trigger has an **Include pre-releases** switch (on by default). When it is off, releases marked as pre-release on GitHub do not fire the trigger.

    **What gets analyzed:** the release tag, name, and notes, the publish time, and repository activity in the hour before it.

    ```json Event data theme={null}
    {
      "eventType": "release",
      "eventAction": "published",
      "data": {
        "tagName": "v2.1.0",
        "name": "Version 2.1.0",
        "body": "Release notes...",
        "prerelease": false,
        "draft": false,
        "publishedAt": "2026-09-02T14:30:00Z",
        "url": "https://github.com/acme/app/releases/tag/v2.1.0"
      }
    }
    ```
  </Tab>

  <Tab title="Push to default branch">
    Fires when commits are pushed to the repository's default branch (usually `main` or `master`). Pushes to other branches, and pushes with no commits, are ignored.

    **GitHub action that fires it:**

    * `pushed`

    **What gets analyzed:** the commit messages, authors, and timestamps in the push, the head commit, and repository activity in the hour before the last commit.

    ```json Event data theme={null}
    {
      "eventType": "push",
      "eventAction": "pushed",
      "data": {
        "ref": "refs/heads/main",
        "branch": "main",
        "commits": [
          {
            "id": "abc123",
            "message": "feat: add exports",
            "author": { "name": "Jane", "email": "jane@acme.com" },
            "timestamp": "2026-09-02T10:00:00Z",
            "url": "https://github.com/acme/app/commit/abc123"
          }
        ],
        "headCommit": { "id": "abc123", "message": "feat: add exports" }
      }
    }
    ```
  </Tab>
</Tabs>

<Note>
  Event triggers are GitHub-only. Linear is a source for [schedules](/automation/scheduled) and on-demand generation, not for event triggers.
</Note>

## Set up the repository webhook

Kolaria receives events through a webhook you add to each repository. Installing the GitHub App connects the repository; the webhook is a separate, one-time step per repository.

<Steps>
  <Step title="Open the repository in Kolaria">
    Go to **Integrations > GitHub** and open the repository. The **Webhook** section reads "Receive events from GitHub when commits are pushed or releases are published."
  </Step>

  <Step title="Generate a secret">
    Click generate. Kolaria shows the **Payload URL**, the **Content type** (`application/json`), and the **Secret** with copy buttons. You can regenerate the secret later; update GitHub when you do.
  </Step>

  <Step title="Add the webhook in GitHub">
    In the repository's **Settings > Webhooks**, add a webhook with the payload URL, content type, and secret from Kolaria. Select the **Releases** and **Pushes** events (or "Send me everything"), then save.
  </Step>

  <Step title="Confirm in Kolaria">
    Click **I've added the webhook**. GitHub's webhook page shows each delivery and Kolaria's response, which is the quickest way to debug a setup.
  </Step>
</Steps>

## Create an event trigger

<Steps>
  <Step title="Open Automation > Events">
    Click **New event trigger**.
  </Step>

  <Step title="Choose the trigger event">
    Pick **Release published** or **Push to default branch**. For releases, decide whether to include pre-releases.
  </Step>

  <Step title="Select repositories">
    Choose one or more connected repositories. The trigger fires for events from any of them.
  </Step>

  <Step title="Choose the content format">
    Changelog entry, blog post, LinkedIn post, tweet, or image.
  </Step>

  <Step title="Pick a brand identity and auto-publish">
    Use the default brand identity or pin one. Auto-publish is available for changelogs and blog posts; when it is on, posts are published immediately instead of saved as drafts.
  </Step>

  <Step title="Save">
    New triggers start enabled. Kolaria rejects a trigger that duplicates an existing one ("Trigger already exists").
  </Step>
</Steps>

### Through the API

The same trigger through the public API (scope `event-triggers.write`):

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.kolaria.com/v1/event-triggers \
    -H "Authorization: Bearer $KOLARIA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sourceType": "github_webhook",
      "sourceConfig": { "eventTypes": ["release"], "includePreReleases": false },
      "targets": { "repositoryIds": ["repo_123"] },
      "outputType": "linkedin_post",
      "outputConfig": { "brandVoiceId": "brand_abc" },
      "enabled": true,
      "autoPublish": false
    }'
  ```

  ```typescript fetch theme={null}
  const response = await fetch("https://api.kolaria.com/v1/event-triggers", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KOLARIA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      sourceType: "github_webhook",
      sourceConfig: { eventTypes: ["release"], includePreReleases: false },
      targets: { repositoryIds: ["repo_123"] },
      outputType: "linkedin_post",
      outputConfig: { brandVoiceId: "brand_abc" },
      enabled: true,
      autoPublish: false,
    }),
  });
  const { eventTrigger } = await response.json();
  ```
</CodeGroup>

`repositoryIds` are GitHub integration IDs from `GET /v1/integrations`. `eventTypes` accepts `release` and `push`; the dashboard creates one event type per trigger, but the API accepts both in one trigger. `outputType` is one of `changelog`, `blog_post`, `linkedin_post`, `twitter_post`, or `image`. List, read, update, and delete with `GET /v1/event-triggers`, `GET`/`PATCH`/`DELETE /v1/event-triggers/{triggerId}`. A `PATCH` takes the full body. A duplicate configuration returns `409`.

## Content generation context

When an event fires, the run builds its prompt from:

* **Event details**: type, action, and a sanitized copy of the event data. Kolaria strips the payload down to known fields and instructs the model to treat it as data, never as instructions.
* **Repository activity**: the hour leading up to the event timestamp (the release publish time, or the latest commit timestamp in the push).
* **Brand identity**: tone, audience, company details, and custom instructions from the selected or default brand identity.

## Security and validation

<AccordionGroup>
  <Accordion title="Signature verification">
    Every delivery must carry a valid `X-Hub-Signature-256` HMAC SHA-256 signature computed with the repository's webhook secret. Requests without a valid signature are rejected and logged.
  </Accordion>

  <Accordion title="Duplicate detection">
    Deliveries are deduplicated by GitHub's `X-GitHub-Delivery` ID for 24 hours. A redelivered event does not generate content twice.
  </Accordion>

  <Accordion title="Payload sanitization">
    Only known fields are extracted from the payload, string lengths are capped, and the model is told the event context is untrusted input.
  </Accordion>

  <Accordion title="Repository and trigger matching">
    Each webhook URL is bound to one organization, integration, and repository. Events are dropped when the integration is disabled, and a trigger only fires when it is enabled and lists that repository.
  </Accordion>
</AccordionGroup>

## Testing a trigger

Event triggers do not have a **Run now** action; they fire only from GitHub. To test one, publish a release (a pre-release works if the trigger includes pre-releases) or push a small commit to the default branch, then check **Content** for the draft and **Settings > Logs** for the delivery.

## Monitoring

* **Settings > Logs** lists integration events with their delivery status, including rejected signatures, duplicate deliveries, and payload validation errors.
* **Settings > Notifications** can email you when automated content is created, when generation fails, and when a run is skipped.
* GitHub's own **Recent Deliveries** view on the webhook shows every request and Kolaria's response code.

## Common use cases

<CardGroup cols={2}>
  <Card title="Release announcements" icon="megaphone">
    Generate a LinkedIn post or tweet whenever you publish a GitHub release.
  </Card>

  <Card title="Continuous changelog" icon="list">
    Create a changelog entry for every push to the default branch, auto-published to your changelog.
  </Card>

  <Card title="Launch blog posts" icon="rocket">
    Draft a blog post for major releases to support product launches.
  </Card>

  <Card title="Release visuals" icon="image">
    Generate a brand-matched social image for each release to pair with the announcement.
  </Card>
</CardGroup>

## Best practices

<AccordionGroup>
  <Accordion title="Filter strategically">
    Release triggers produce far fewer runs than push triggers. Use releases for announcements and reserve push triggers for changelogs.
  </Accordion>

  <Accordion title="Mind your quota">
    Each run uses the plan quota for its format (long-form for changelogs and blog posts, social for LinkedIn and X, image generations for images). A push trigger on a busy repository can use quota quickly.
  </Accordion>

  <Accordion title="Combine with scheduling">
    Use event triggers for immediate announcements and a weekly schedule for digests that cover everything else.
  </Accordion>

  <Accordion title="Keep secrets in sync">
    If you regenerate a webhook secret in Kolaria, update the GitHub webhook right away. Deliveries signed with the old secret are rejected.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhooks not received">
    **Check:**

    * The webhook exists in the repository's GitHub settings with the payload URL from Kolaria
    * The content type is `application/json`
    * The secret matches the one shown in Kolaria
    * The repository integration is enabled in Kolaria

    GitHub's Recent Deliveries view shows the response Kolaria returned for each attempt.
  </Accordion>

  <Accordion title="Content not generated">
    **Check:**

    * The event type matches the trigger (a push to a feature branch never fires)
    * The release is not a draft, and pre-releases are included if the release is one
    * The repository is in the trigger's target list
    * The trigger is enabled (Active tab, not Paused)
    * You still have quota or AI credits for that format

    If the run found nothing worth writing about it is recorded as skipped; enable the Skipped notification to hear about it.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Scheduled automation" icon="calendar" href="/automation/scheduled">
    Time-based content generation with lookback windows
  </Card>

  <Card title="Brand voice" icon="palette" href="/concepts/brand-voice">
    Customize how generated content sounds
  </Card>
</CardGroup>