How do I put JSON API endpoints beside GitHub commits and pull requests?

Tares puts a JSON API endpoint beside GitHub commits and pull requests when both sources carry the same label value and that label is marked as the key. Choose a value both sides have, such as a repository or service name, and set it as the primary label on the github source and the http_poll source. Events from both then land on one timeline for that entity.

How it works

Tares builds one timeline per key value. Sources that carry the same primary label value merge onto the same timeline, on one clock. That is how the AI SRE guide lines up metrics, logs and alerts per service.

Two connectors do the work here:

• github polls a repository’s commits and pull requests every 2 minutes with a personal token. Every GitHub event carries a repo label in the form owner/name, such as acme/checkout-api. With the GitHub App, events arrive by webhook for every repository the App is installed on, and they carry the same repo label.
• http_poll calls a JSON endpoint on a schedule and stores one event per item. Nested values are reachable by dotted name, so a label can read a field of the reply or a fixed value.

The join is a label value you choose. The GitHub repo label reads acme/checkout-api, so give the API source a label whose value is the same string. The label can be a const you write, or a field from the reply when the endpoint returns the repository or service name itself. Mark that label primary: true on both sources.

If you also want rows that changed after a commit or deploy, a Postgres table source works the same way. Its entity column becomes the key through a primary label, so a repo or service column lines up with the same value.

Set it up

1. Pick the shared key. Use the value GitHub already produces, the owner/name of the repository, or a service name you control, and make sure each source can emit it.
2. Add the GitHub source. With a personal token, add one source per repository under Sources > Add source > GitHub, pick the credential and the repository, and save. The label repo is the key:

- name: checkout-api
  connector: github
  poll: 2m
  config:
    repo: acme/checkout-api
    credential: github
    labels:
      - { name: repo, field: repo, primary: true }

3. Add the JSON API source under Sources > Add source > HTTP API (poll). Press Discover so Tares calls the endpoint once and shows the reply. Give it a repo label with the same value as the GitHub source and mark it primary:

- name: checkout_api_readings
  connector: http_poll
  poll: 10m
  config:
    url: https://api.example.com/v1/readings
    event_type: api_reading
    labels:
      - { name: repo, const: acme/checkout-api, primary: true }

4. If the endpoint needs a credential, put it in credential and name the header in credential_header. Tares stores the credential as a secret.
5. Keep poll at 10 seconds or more. The connector refuses anything shorter when the source is saved.
6. Verify. Open each source: Recent events shows what each poll stored, and Fields lists every field seen with its coverage. Use Fields to confirm the repo label is present on every event.
7. Open Explore and pick acme/checkout-api. Commits, pull requests and API events appear together in time order.

If you use the GitHub App, one github source covers every repository it is installed on. The repo label still carries the repository name, so the same shared value works.

What you get

• One timeline per repository or service, with commits and pull requests next to the readings from your JSON API.
• A clear view of what happened on the API side after a merge or push, because both sit on the same clock.
• Pull request events with the labels action, author, branch, sha, title and url, so you can see which change came before a shift in the API data.
• An http_poll source that deduplicates by id_field, so an unchanged reading is not stored again.
• Backoff on 429 and 5xx replies from the API, with the reason shown in the source’s health.
• The same timeline for any agent you connect, since agents read the correlated timeline for an entity.

When something else fits

• If the API pushes to you, for example a CI system that calls out on every deploy, the webhook connector fits better than http_poll, which is for APIs Tares calls.
• If the changes you care about are rows in your own database, use the Postgres connector instead of an API endpoint.
• If you want pushes, reviews, releases and CI runs rather than polled commits and pull requests, connect the GitHub App described on the GitHub page. For the full setup, see HTTP API (poll).

Related