Support querying runs via API

RFCs
1

Need/problem

A couple months ago, we released our own GitHub app to share Tuist Reports directly in PRs with information such as test results or links to Tuist Previews.

However, some teams either:

  • Want to create Tuist Reports using their own GitHub app, for example, when the organization already has one and they want to limit the number of automated comments in a single PR.
  • Don’t use GitHub (we could integrate other platforms such as GitLab, but we can’t integrate with every platform out there)

To enable this flow, I am proposing to add a new REST API endpoint for listing runs and add the possibility to filter runs associated with a given PR. That can not only be used by custom reporters, but it can enable other use cases we haven’t thought of, yet.

Detailed design

I’m proposing to add a new endpoint /api/:account_handle/:project_handle/runs that would return a list of runs:

{
  "runs": [
    {
      "name": "test",
      "status": "success",
      "test_targets": ["A", "B"],
      "local_test_targets_hits": [],
      "remote_test_targets_hits": ["A"],
      "git_commit_sha": "87decdka",
      "git_ref": "refs/pull/23958/merge",
      "git_branch": "feature/my-feature",
      "inserted_at": "2025-01-06T11:00:00.256073"
    },
    ...
  ]
}

To get runs for a given PR, a filter would be available:

https://tuist.dev/api/runs?git_ref="refs/pull/23943/merge"

Developers could then add an action that runs after arbitrary tuist command is invoked that would:

  • Get runs for a given PR
  • Format their own reporter message
  • Use their own bot to post or update a PR message

To authenticate, they could use the project token.

Drawbacks

There’s some extra API surface that we’d need to support, but long-term, we’d probably end up adding an endpoint for runs regardless.

Alternatives

We could add direct support in the Tuist CLI to either output the report message or the list of the runs. However, that would add some additional complexity, so I’m leaning to start with an API endpoint only.

How we teach this

The new API endpoint would be documented as any other endpoint.

We would also add a note in the integrations page for how to use the API to build your own reports bot.

2

@marekfort what would the response of an individual run look like?

3

The proposed schema is here. I might be missing some fields that I’d end up adding.

Or do you mean something else?

4

If the use case is having data to generate their own reports, what do they want to include in those reports? The data in the schema reads very barebones, but it might already be covering what they need.

5

The point was not to be exhaustive with the schema. We will include more data (reflecting what we have in the database)

1 Like