Skip to content
KontruaDocs
Get started

CI / API Trigger

Trigger context runs directly from any CI pipeline.

The API trigger lets you invoke Kontrua from GitHub Actions, GitLab CI, or any shell script. This is useful if you want the context to update on every push rather than on PR approval, or if you prefer to control the trigger yourself.

Create an API token

API tokens are per-repository. Go to Dashboard - [your repo] - Integration and click Generate token. The raw token is shown once - copy it immediately. Kontrua stores only a hash, so you cannot retrieve it again.

Store the token as a secret in your CI environment (PITH_API_TOKEN). Never commit it to your repository.

Endpoint

POST /api/trigger
POST /api/trigger
Authorization: Bearer <token>
Content-Type: application/json

{
  "beforeSha": "<parent-commit-sha>",   // required - 7-40 hex chars
  "afterSha":  "<head-commit-sha>",     // required - 7-40 hex chars
  "prHeadBranch": "<branch-name>"       // optional - enables pre-merge mode
}

Post-merge vs pre-merge mode

Kontrua supports two delivery modes controlled by whether you include prHeadBranch in the request:

ModeHow to useResult
Post-mergeOmit prHeadBranchKontrua opens a separate PR targeting your main branch with the updated context artifacts and doc views
Pre-mergeInclude prHeadBranchKontrua commits the updates directly to that branch so the context ships in the same PR as the code

GitHub Actions

.github/workflows/context.yml
name: Update repo context with Kontrua

on:
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Kontrua
        run: |
          curl -sS -X POST ${{ vars.PITH_URL }}/api/trigger \
            -H "Authorization: Bearer ${{ secrets.PITH_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{
              "beforeSha": "${{ github.event.before }}",
              "afterSha":  "${{ github.sha }}"
            }'

For pre-merge mode (context updates included in the same PR):

.github/workflows/context-pre-merge.yml
name: Update repo context with Kontrua (pre-merge)

on:
  pull_request:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Kontrua
        run: |
          curl -sS -X POST ${{ vars.PITH_URL }}/api/trigger \
            -H "Authorization: Bearer ${{ secrets.PITH_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{
              "beforeSha":    "${{ github.event.pull_request.base.sha }}",
              "afterSha":     "${{ github.event.pull_request.head.sha }}",
              "prHeadBranch": "${{ github.head_ref }}"
            }'

GitLab CI

.gitlab-ci.yml
update-context:
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script:
    - |
      curl -sS -X POST $PITH_URL/api/trigger \
        -H "Authorization: Bearer $PITH_API_TOKEN" \
        -H "Content-Type: application/json" \
        -d "{
          \"beforeSha\": \"$CI_COMMIT_BEFORE_SHA\",
          \"afterSha\":  \"$CI_COMMIT_SHA\"
        }"

Response

StatusBodyMeaning
200{ "ok": true, "runId": "...", "runUrl": "..." }Run created successfully
200{ "error": "quota_exceeded", "usage": {...} }Monthly limit reached - run is queued
401{ "error": "unauthorized" }Token missing or invalid
429{ "error": "rate_limit" }Too many requests (30 req/min per token)

Ready to keep your repo's context current?

Connect your first repository and Kontrua opens a reviewed PR with AGENTS.md, a codemap, and your conventions.

Get started for freeView pricing