secondshift 0.1.0b12__py3-none-any.whl

secondshift/runs/transitions.py

@@ -0,0 +1,84 @@
+"""The only code that changes a run's status.
+
+A run goes from queued to running, then succeeds, fails or is canceled. A
+queued run can also fail or be canceled before it starts. A finished run
+never changes again.
+"""
+
+from collections.abc import Collection, Mapping
+
+from django.db import transaction
+from django.utils import timezone
+
+from secondshift.config.constants import RunSandbox
+from secondshift.gateway.dao import revoke_run_tokens
+from secondshift.runs.dao import lock_run_in
+from secondshift.runs.models import Run, RunFailure
+
+# The statuses each status may move to. A finished status has no entry.
+NEXT_STATUSES: dict[str, frozenset[str]] = {
+    Run.Status.QUEUED: frozenset(
+        {Run.Status.RUNNING, Run.Status.FAILED, Run.Status.CANCELED}
+    ),
+    Run.Status.RUNNING: frozenset(
+        {Run.Status.SUCCEEDED, Run.Status.FAILED, Run.Status.CANCELED}
+    ),
+}
+
+
+class TransitionRefused(Exception):
+    pass
+
+
+def can_move(current: str, new: str) -> bool:
+    return new in NEXT_STATUSES.get(current, frozenset())
+
+
+def mark_running(run_id: int, workflow_id: str) -> bool:
+    """Move a queued run to running. False when the run is not queued."""
+    # Status writes stay in this module, so it is the only place they happen.
+    return bool(
+        Run.objects.filter(pk=run_id, status=Run.Status.QUEUED).update(
+            status=Run.Status.RUNNING,
+            started_at=timezone.now(),
+            sandbox_runtime=RunSandbox.PENDING,
+            dbos_workflow_id=workflow_id,
+        )
+    )
+
+
+@transaction.atomic
+def finish_run(
+    run_id: int,
+    status: str,
+    summary: str,
+    *,
+    only_from: Collection[str] = Run.ACTIVE_STATUSES,
+    fields: Mapping[str, object] | None = None,
+    failure: RunFailure = RunFailure.OTHER,
+    reason: str = "",
+) -> Run | None:
+    """Give a run its final status, summary and finish time, and revoke its tokens.
+
+    Returns None and changes nothing when the run is not in `only_from`,
+    usually because it already finished. `fields` are saved with the status.
+    A failed run also records why. The reason defaults to the summary.
+    """
+    if status in Run.ACTIVE_STATUSES:
+        raise TransitionRefused(f"{status} is not a final status.")
+    run = lock_run_in(run_id, only_from)
+    if run is None:
+        return None
+    if not can_move(run.status, status):
+        raise TransitionRefused(f"A {run.status} run cannot become {status}.")
+    extra = dict(fields or {})
+    if status == Run.Status.FAILED:
+        extra |= {"failure": failure, "failure_reason": reason or summary}
+    run.status = status
+    run.summary = summary
+    run.finished_at = timezone.now()
+    for name, value in extra.items():
+        setattr(run, name, value)
+    run.save(update_fields=["status", "summary", "finished_at", *extra])
+    revoke_run_tokens(run_id)
+    return run

secondshift/templates/account/password_reset_help_text.html

@@ -0,0 +1 @@
+{% load accounts %}{% password_reset_link %}

secondshift/templates/admin/base_site.html

@@ -0,0 +1,24 @@
+{% extends "admin/base.html" %}
+{% load static %}
+
+{% block title %}{% if subtitle %}{{ subtitle }} | {% endif %}{{ title }} | {{ site_title }}{% endblock %}
+
+{% block extrahead %}
+<link rel="icon" type="image/svg+xml" href="{% static 'favicon.svg' %}">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=Geist+Mono:wght@400;500&display=swap">
+{% endblock %}
+
+{% block extrastyle %}<link rel="stylesheet" href="{% static 'core/admin.css' %}">{% endblock %}
+
+{% block branding %}
+<div id="site-name">
+  <a href="{% url 'admin:index' %}" class="ss-brand">
+    <img src="{% static 'secondshift-mark.svg' %}" alt="" width="32" height="32">
+    <span>{{ site_header }}</span>
+  </a>
+</div>
+{% endblock %}
+
+{% block nav-global %}{% endblock %}

secondshift/templates/allauth/elements/provider.html

@@ -0,0 +1,9 @@
+{% load i18n %}
+<li>
+  <a class="account-provider" title="{{ attrs.name }}" href="{{ attrs.href }}">
+    {% if attrs.provider_id == "github" %}
+      <svg viewBox="0 0 24 24" width="18" height="18" aria-hidden="true"><path fill="currentColor" d="M12,2A10,10 0 0,0 2,12C2,16.42 4.87,20.17 8.84,21.5C9.34,21.58 9.5,21.27 9.5,21C9.5,20.77 9.5,20.14 9.5,19.31C6.73,19.91 6.14,17.97 6.14,17.97C5.68,16.81 5.03,16.5 5.03,16.5C4.12,15.88 5.1,15.9 5.1,15.9C6.1,15.97 6.63,16.93 6.63,16.93C7.5,18.45 8.97,18 9.54,17.76C9.63,17.11 9.89,16.67 10.17,16.42C7.95,16.17 5.62,15.31 5.62,11.5C5.62,10.39 6,9.5 6.65,8.79C6.55,8.54 6.2,7.5 6.75,6.15C6.75,6.15 7.59,5.88 9.5,7.17C10.29,6.95 11.15,6.84 12,6.84C12.85,6.84 13.71,6.95 14.5,7.17C16.41,5.88 17.25,6.15 17.25,6.15C17.8,7.5 17.45,8.54 17.35,8.79C18,9.5 18.38,10.39 18.38,11.5C18.38,15.32 16.04,16.16 13.81,16.41C14.17,16.72 14.5,17.33 14.5,18.26C14.5,19.6 14.5,20.68 14.5,21C14.5,21.27 14.66,21.59 15.17,21.5C19.14,20.16 22,16.42 22,12A10,10 0 0,0 12,2Z"/></svg>
+    {% endif %}
+    <span>{% blocktrans with provider=attrs.name %}Continue with {{ provider }}{% endblocktrans %}</span>
+  </a>
+</li>

secondshift/templates/allauth/layouts/base.html

@@ -0,0 +1,67 @@
+{% load i18n static %}
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{% block head_title %}{% endblock head_title %} · SecondShift</title>
+    <link rel="icon" type="image/svg+xml" href="{% static 'favicon.svg' %}">
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap">
+    <link rel="stylesheet" href="{% static 'core/account.css' %}">
+    {% block extra_head %}{% endblock extra_head %}
+  </head>
+  <body>
+    {% block body %}
+      <main class="account-page">
+        <section class="account-card">
+          <a href="/" class="account-brand">
+            <img src="{% static 'secondshift-mark.svg' %}" alt="" width="32" height="32">
+            <span>SecondShift</span>
+          </a>
+          <span class="account-eyebrow">{% trans "Your agents, safely on duty" %}</span>
+          {% if messages %}
+            <ul class="account-messages">
+              {% for message in messages %}<li>{{ message }}</li>{% endfor %}
+            </ul>
+          {% endif %}
+          {% if pending_invite and not user.is_authenticated %}
+            <p class="account-invite">
+              {% blocktrans with workspace=pending_invite.workspace.name role=pending_invite.get_role_display %}Sign in or sign up to join <strong>{{ workspace }}</strong> as {{ role }}.{% endblocktrans %}
+            </p>
+          {% endif %}
+          {% block content %}{% endblock content %}
+          {% if user.is_authenticated %}
+            <a href="/" class="account-back">{% trans "Back to SecondShift" %}</a>
+          {% endif %}
+        </section>
+        <aside class="account-atmosphere" aria-label="{% trans "Example scheduled reviews" %}">
+          <ol class="shift-schedule">
+            <li class="shift-preview">
+              <time>Mon 09:00</time>
+              <div><strong>Weekly release recap</strong><p>Merged features, fixes, and what comes next.</p></div>
+            </li>
+            <li class="shift-preview">
+              <time>Daily 08:00</time>
+              <div><strong>CI failure review</strong><p>Recurring failures and suggested fixes.</p></div>
+            </li>
+            <li class="shift-preview">
+              <time>Mon 09:15</time>
+              <div><strong>Repository health review</strong><p>Defects, test gaps, and docs that drifted.</p></div>
+            </li>
+            <li class="shift-preview">
+              <time>Mon 09:30</time>
+              <div><strong>Alert coverage review</strong><p>Removed alerts, paused rules, and changed thresholds.</p></div>
+            </li>
+            <li class="shift-preview">
+              <time>Fri 16:00</time>
+              <div><strong>Contributor recap</strong><p>The people behind the work and reviews.</p></div>
+            </li>
+          </ol>
+        </aside>
+      </main>
+    {% endblock body %}
+    {% block extra_body %}{% endblock extra_body %}
+  </body>
+</html>

secondshift/templates/socialaccount/snippets/login.html

@@ -0,0 +1,9 @@
+{% load i18n allauth socialaccount %}
+{% get_providers as socialaccount_providers %}
+{% if socialaccount_providers %}
+  {% if not SOCIALACCOUNT_ONLY %}
+    <hr>
+  {% endif %}
+  {% include "socialaccount/snippets/provider_list.html" with process="login" %}
+  {% include "socialaccount/snippets/login_extra.html" %}
+{% endif %}

secondshift/templates/workspaces/invite_unusable.html

@@ -0,0 +1,10 @@
+{% extends "allauth/layouts/base.html" %}
+{% load i18n %}
+{% block head_title %}{% trans "Invite link" %}{% endblock head_title %}
+{% block content %}
+  <h1>{% trans "This invite link no longer works" %}</h1>
+  <p>{{ message }}</p>
+  {% if not user.is_authenticated %}
+    <p><a href="{% url 'account_login' %}">{% trans "Sign in" %}</a></p>
+  {% endif %}
+{% endblock content %}

secondshift/triggers/admin.py

@@ -0,0 +1,19 @@
+from django.contrib import admin
+
+from secondshift.triggers.models import JobTrigger, TriggerEvent
+
+
+@admin.register(JobTrigger)
+class JobTriggerAdmin(admin.ModelAdmin):
+    list_display = ("job", "kind", "enabled", "secret_rotated_at")
+    list_filter = ("kind", "enabled")
+    # The secret is never shown. Rotate it from the dashboard.
+    exclude = ("secret",)
+    readonly_fields = ("job", "kind", "public_id", "secret_rotated_at")
+
+
+@admin.register(TriggerEvent)
+class TriggerEventAdmin(admin.ModelAdmin):
+    list_display = ("trigger", "outcome", "reason", "run", "received_at")
+    list_filter = ("outcome",)
+    readonly_fields = ("trigger", "outcome", "reason", "run", "received_at")

secondshift/triggers/api.py

@@ -0,0 +1,116 @@
+import logging
+
+from django.conf import settings
+from django.http import HttpRequest, HttpResponse
+from ninja import Router, Status
+from ninja.errors import HttpError
+from ninja.security import django_auth
+
+from secondshift.config.constants import TriggerKind
+from secondshift.jobs.access import job_for_request
+from secondshift.triggers.dao import trigger_for_url
+from secondshift.triggers.schemas import (
+    TriggerChangeSchema,
+    TriggerEnabledSchema,
+    TriggerLimitSchema,
+    TriggerReceivedSchema,
+    TriggerSchema,
+)
+from secondshift.triggers.serialization import (
+    serialize_change,
+    serialize_job_triggers,
+    serialize_trigger,
+)
+from secondshift.triggers.services import (
+    TriggerError,
+    receive,
+    rotate_secret,
+    set_runs_per_hour,
+    set_trigger_enabled,
+)
+from secondshift.workspaces.access import Action, require
+
+logger = logging.getLogger(__name__)
+
+router = Router(auth=django_auth, tags=["triggers"])
+
+
+@router.get("/jobs/{job_id}/triggers", response=list[TriggerSchema])
+def job_triggers(request: HttpRequest, job_id: int) -> list[TriggerSchema]:
+    return serialize_job_triggers(job_for_request(request, job_id))
+
+
+@router.post("/jobs/{job_id}/triggers/{kind}/enabled", response=TriggerChangeSchema)
+def set_enabled(
+    request: HttpRequest, job_id: int, kind: TriggerKind, payload: TriggerEnabledSchema
+) -> TriggerChangeSchema:
+    job = job_for_request(request, job_id)
+    require(request, Action.MANAGE_TRIGGERS)
+    try:
+        change = set_trigger_enabled(job, kind, payload.enabled)
+    except TriggerError as error:
+        raise HttpError(409, str(error)) from error
+    return serialize_change(job, change)
+
+
+@router.post("/jobs/{job_id}/triggers/{kind}/rotate", response=TriggerChangeSchema)
+def rotate(request: HttpRequest, job_id: int, kind: TriggerKind) -> TriggerChangeSchema:
+    job = job_for_request(request, job_id)
+    require(request, Action.MANAGE_TRIGGERS)
+    try:
+        change = rotate_secret(job, kind)
+    except TriggerError as error:
+        raise HttpError(409, str(error)) from error
+    return serialize_change(job, change)
+
+
+@router.post("/jobs/{job_id}/triggers/{kind}/limit", response=TriggerSchema)
+def set_limit(
+    request: HttpRequest, job_id: int, kind: TriggerKind, payload: TriggerLimitSchema
+) -> TriggerSchema:
+    job = job_for_request(request, job_id)
+    require(request, Action.MANAGE_TRIGGERS)
+    try:
+        trigger = set_runs_per_hour(job, kind, payload.runs_per_hour)
+    except TriggerError as error:
+        raise HttpError(409, str(error)) from error
+    return serialize_trigger(job, kind, trigger)
+
+
+@router.post(
+    "/triggers/{public_id}",
+    auth=None,
+    response={
+        frozenset({200, 202, 401, 409, 413, 429, 503}): TriggerReceivedSchema,
+    },
+    include_in_schema=False,
+)
+def receive_trigger(
+    request: HttpRequest, response: HttpResponse, public_id: str
+) -> Status[TriggerReceivedSchema]:
+    """The public URL a webhook calls. Its secret is the only sign-in."""
+    trigger = trigger_for_url(public_id)
+    if trigger is None:
+        raise HttpError(404, "Not found.")
+    length = int(request.headers.get("Content-Length") or 0)
+    if length > settings.TRIGGER_MAX_BODY_BYTES:
+        return Status(
+            413, TriggerReceivedSchema(detail="The request body is too large.")
+        )
+    body = request.body
+    if len(body) > settings.TRIGGER_MAX_BODY_BYTES:
+        return Status(
+            413, TriggerReceivedSchema(detail="The request body is too large.")
+        )
+    received = receive(trigger, request.headers, body)
+    if received.status != 202:
+        logger.info("trigger %s did not start a run: %s", trigger.pk, received.detail)
+    if received.retry_after is not None:
+        response["Retry-After"] = str(received.retry_after)
+    return Status(
+        received.status,
+        TriggerReceivedSchema(
+            detail=received.detail,
+            run_id=received.run.pk if received.run else None,
+        ),
+    )

secondshift/triggers/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class TriggersConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "secondshift.triggers"

secondshift/triggers/dao.py

@@ -0,0 +1,66 @@
+"""Queries and writes on job triggers and the requests they receive."""
+
+from datetime import datetime
+
+from django.db import transaction
+
+from secondshift.jobs.models import Job
+from secondshift.runs.models import Run
+from secondshift.triggers.models import JobTrigger, TriggerEvent
+
+
+def trigger_for_url(public_id: str) -> JobTrigger | None:
+    """The trigger behind a public webhook URL, with its job and repository."""
+    return (
+        JobTrigger.objects.select_related("job__repository")
+        .filter(public_id=public_id)
+        .first()
+    )
+
+
+def job_trigger(job: Job, kind: str) -> JobTrigger | None:
+    """The job's trigger of this kind, if it was ever set up."""
+    return JobTrigger.objects.filter(job=job, kind=kind).first()
+
+
+def create_trigger(
+    job: Job, kind: str, secret: str, secret_rotated_at: datetime
+) -> JobTrigger:
+    """Set up an enabled trigger with its first secret."""
+    return JobTrigger.objects.create(
+        job=job,
+        kind=kind,
+        secret=secret,
+        enabled=True,
+        secret_rotated_at=secret_rotated_at,
+    )
+
+
+def add_event(
+    trigger: JobTrigger, outcome: str, reason: str, run: Run | None, keep: int
+) -> None:
+    """Record a request, keeping only the newest `keep` events of its outcome."""
+    with transaction.atomic():
+        TriggerEvent.objects.create(
+            trigger=trigger, outcome=outcome, reason=reason, run=run
+        )
+        stale = (
+            trigger.events.filter(outcome=outcome)
+            .order_by("-received_at", "-pk")
+            .values_list("pk", flat=True)[keep:]
+        )
+        TriggerEvent.objects.filter(pk__in=list(stale)).delete()
+
+
+def has_recent_event(
+    trigger: JobTrigger, outcome: str, reason: str, since: datetime
+) -> bool:
+    """Whether the trigger recorded this outcome and reason since then."""
+    return trigger.events.filter(
+        outcome=outcome, reason=reason, received_at__gte=since
+    ).exists()
+
+
+def recent_events(trigger: JobTrigger, limit: int) -> list[TriggerEvent]:
+    """The trigger's newest requests, newest first."""
+    return list(trigger.events.all()[:limit])

secondshift/triggers/filters.py

@@ -0,0 +1,48 @@
+"""Read a webhook body against the job's webhook settings.
+
+The settings name fields in the sender's own format, such as Grafana's
+"status" or "groupKey". Nothing here knows any sender.
+"""
+
+import hashlib
+import json
+from typing import Any
+
+MISSING = object()
+
+
+def parse_body(body: bytes) -> Any:
+    try:
+        return json.loads(body)
+    except (UnicodeDecodeError, ValueError):
+        return None
+
+
+def field_value(data: Any, path: str) -> Any:
+    """The value at a dotted path, or MISSING."""
+    for part in path.split("."):
+        if not isinstance(data, dict) or part not in data:
+            return MISSING
+        data = data[part]
+    return data
+
+
+def skip_reason(data: Any, skip_when: dict[str, Any]) -> str | None:
+    """Why the body matches skip_when, or None. Every field must match."""
+    if not skip_when:
+        return None
+    if all(field_value(data, path) == value for path, value in skip_when.items()):
+        matched = ", ".join(f"{path} is {value}" for path, value in skip_when.items())
+        return f"Skipped by the job's settings: {matched}."
+    return None
+
+
+def repeat_key(data: Any, path: str | None) -> str | None:
+    """A hash of the repeat_key field's value. None when it is not set or absent."""
+    if not path:
+        return None
+    value = field_value(data, path)
+    if value is MISSING or value is None:
+        return None
+    canonical = json.dumps(value, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(f"{path}={canonical}".encode()).hexdigest()

secondshift/triggers/migrations/0001_initial.py

@@ -0,0 +1,55 @@
+# Generated by Django 6.0.9 on 2026-11-01 17:26
+
+import django.db.models.deletion
+import encrypted_model_fields.fields
+import secondshift.triggers.models
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('jobs', '0005_job_triggers'),
+        ('runs', '0002_run_started_by'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='JobTrigger',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('kind', models.CharField(choices=[('webhook', 'Webhook')], max_length=16)),
+                ('public_id', models.CharField(default=secondshift.triggers.models.new_public_id, max_length=64, unique=True)),
+                ('secret', encrypted_model_fields.fields.EncryptedTextField()),
+                ('enabled', models.BooleanField(default=False)),
+                ('secret_rotated_at', models.DateTimeField()),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('job', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='job_triggers', to='jobs.job')),
+            ],
+        ),
+        migrations.CreateModel(
+            name='TriggerEvent',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('outcome', models.CharField(choices=[('started', 'Started a run'), ('refused', 'Refused')], max_length=16)),
+                ('reason', models.CharField(blank=True, max_length=500)),
+                ('received_at', models.DateTimeField(auto_now_add=True)),
+                ('run', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='trigger_events', to='runs.run')),
+                ('trigger', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='events', to='triggers.jobtrigger')),
+            ],
+            options={
+                'ordering': ['-received_at', '-pk'],
+            },
+        ),
+        migrations.AddConstraint(
+            model_name='jobtrigger',
+            constraint=models.UniqueConstraint(fields=('job', 'kind'), name='unique_job_trigger_kind'),
+        ),
+        migrations.AddIndex(
+            model_name='triggerevent',
+            index=models.Index(fields=['trigger', 'received_at'], name='trigger_event_received_idx'),
+        ),
+    ]

secondshift/triggers/migrations/0002_ignored_events_and_hourly_limit.py

@@ -0,0 +1,23 @@
+# Generated by Django 6.0.9 on 2026-11-01 18:06
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('triggers', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='jobtrigger',
+            name='max_runs_per_hour',
+            field=models.PositiveIntegerField(blank=True, null=True),
+        ),
+        migrations.AlterField(
+            model_name='triggerevent',
+            name='outcome',
+            field=models.CharField(choices=[('started', 'Started a run'), ('ignored', 'Ignored'), ('refused', 'Refused')], max_length=16),
+        ),
+    ]

secondshift/triggers/models.py

@@ -0,0 +1,83 @@
+import secrets
+
+from django.db import models
+from encrypted_model_fields.fields import EncryptedTextField
+
+from secondshift.config.constants import TriggerKind
+from secondshift.jobs.models import Job
+from secondshift.runs.models import Run
+
+
+def new_public_id() -> str:
+    return secrets.token_urlsafe(24)
+
+
+class JobTrigger(models.Model):
+    """One trigger kind for one job, as an owner or admin set it up.
+
+    The repository only names the kind. The URL, the secret and whether it is
+    on live here and are changed only in the dashboard.
+    """
+
+    job = models.ForeignKey(Job, on_delete=models.CASCADE, related_name="job_triggers")
+    kind = models.CharField(
+        max_length=16,
+        choices=[(item.value, item.value.title()) for item in TriggerKind],
+    )
+    # The last part of the trigger's URL. Random, so it reveals nothing.
+    public_id = models.CharField(max_length=64, unique=True, default=new_public_id)
+    # Encrypted, not hashed: checking an HMAC signature needs the secret itself.
+    secret = EncryptedTextField()
+    enabled = models.BooleanField(default=False)
+    # The owner's cap on runs this trigger starts per hour. Empty uses the
+    # server default.
+    max_runs_per_hour = models.PositiveIntegerField(null=True, blank=True)
+    secret_rotated_at = models.DateTimeField()
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        constraints = [
+            models.UniqueConstraint(
+                fields=["job", "kind"], name="unique_job_trigger_kind"
+            )
+        ]
+
+    def __str__(self) -> str:
+        return f"{self.job}: {self.kind}"
+
+
+class TriggerEvent(models.Model):
+    """One request a trigger received, and what SecondShift did with it."""
+
+    class Outcome(models.TextChoices):
+        STARTED = "started", "Started a run"
+        # Not a run, by the job's own settings: a skipped or repeated event.
+        IGNORED = "ignored", "Ignored"
+        REFUSED = "refused", "Refused"
+
+    trigger = models.ForeignKey(
+        JobTrigger, on_delete=models.CASCADE, related_name="events"
+    )
+    outcome = models.CharField(max_length=16, choices=Outcome.choices)
+    # Why it was ignored or refused, in words for the person who set it up.
+    reason = models.CharField(max_length=500, blank=True)
+    run = models.ForeignKey(
+        Run,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="trigger_events",
+    )
+    received_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        ordering = ["-received_at", "-pk"]
+        indexes = [
+            models.Index(
+                fields=["trigger", "received_at"], name="trigger_event_received_idx"
+            )
+        ]
+
+    def __str__(self) -> str:
+        return f"{self.trigger} at {self.received_at:%Y-%m-%d %H:%M}: {self.outcome}"