Skip to content
Starlite Docs

Integration guide

Starlite can be used without automation support, but it really blooms out when you drive it through automation. This guide helps you set up things to gain maximum benefit from Starlite.

Integration overview

A complete integration involves two parts:

  • Pushing Records and/or Standards, usually done in CI pipelines, e.g. GitHub Actions.
  • Sending Metrics, usually done via webhooks in your Version Control System, e.g. GitHub.

However, at the end of the day, you choose how deep you want to go. The only constant is that you must have a Record if you want to push Standards or Metrics.

The below table explains how Starlite supports your integration needs.

GitHub App (Future)CI workflows (e.g. GitHub Actions, GitLab…)WebhooksManual
Level of accessFile treeSource codeEvent dataSource code
Records✅✅❌✅
Standards✅✅❌⚠️ Yes, but requires running StandardLint (open-source Node.js package) to produce results
DORA metrics⚠️* Yes, if using GH Issues❌✅**⚠️ Yes, but some events require Git/source code access and calculating values
Engineering metrics⚠️* Yes, if using GH Issues❌✅**⚠️ Yes, but some events require Git/source code access and calculating values

* = Can be disabled and complemented with webhooks from your Issue Management System, e.g. Jira.

** = Requires setup according to instructions.

Which tools Starlite supports

With Starlite supporting many common tools, your needs are probably covered well.

Where do you host your Records and Standards?

Records and Standards are pushed (“uploaded”) during your continuous integration process.

This will likely be the same where place you store your code.

Starlite supports:

  • GitHub
  • GitLab
  • Bitbucket
  • Azure DevOps
  • Somewhere else (manual)

Where do you host your issues?

Tracking your issues enables Starlite to gather and present various metrics.

This will likely be your regular issue tracker, if you are using such a tool.

Starlite supports:

  • GitHub
  • GitLab
  • Bitbucket
  • Azure DevOps
  • Jira
  • Linear
  • Somewhere else (manual)

Can I use different tools for code and issues?

Yes, that’s entirely possible!

Records and Standards

Records constitute the central feature of Starlite, supporting your needs around documenting software. Records must be in an automated lifecycle in order for updates to take place via automation.

Standards let you see how the technical context presented in a Record conforms to your organizational Standards. Standards can only be updated via automation; they cannot be updated in the Starlite user interface.

How to handle Records and Standards

In an automated lifecycle, the information displayed in Starlite’s Records are stored in a structured JSON file: This is called the manifest file and is always named starlite.manifest.json. You keep and lifecycle-manage this manifest file in a Git repository.

The recommended way to store and manage the manifest file is to follow standard developer conventions:

  1. Store the manifest file in a Git repository.
  • For custom-developed software, this will be the same Git repository as the Record logically refers to, e.g. your Record representing My API might be in a repository called my-api. Note that the repository name is not used by Starlite; this is just stated for your own convenience.
  • For other software, e.g. SaaS or externally-provided software, you will have to decide on a way that suits your needs and organization. For example, this repository could be a new repository only containing the manifest file. This way you get a 1:1 relation between a piece of software and the context that drives updates, i.e. the CI run and Starlite integration. Note that Starlite won’t care about how you do this, so find the way that is best for you.
  1. Update the Record via the integration method provided for your Version Control System. This is ideally done during your continuous integration workflow, such as when the pipeline for the main branch runs.

Integrating Records and Standards

To avoid hardcoding sensitive information, configure variables in the repository settings.

The following assumes the use of GitHub Actions.

  1. Navigate to your repository and go to Settings > Secrets and variables > Actions.
  2. For each of the following required variables, create a new secret with the listed name and your corresponding value for it:
  • STARLITE_API_KEY: Your Starlite API key.
  • STARLITE_ORG_ID: (Optional) Your Organization ID. Will be inferred from the organizationId in the manifest file if not explicitly provided.
  • STARLITE_RECORD_ID: (Optional) The Record ID. Will be inferred from the id in the manifest file if not explicitly provided.

You can also optionally add:

  • RUN_RECORD and RUN_STANDARDS: These should default to true.
  • RUN_DEPLOYMENT: This should default to false.

Now, the only remaining thing to do is to use the starlite-action GitHub Action in your workflows!

Here’s an example of using the Starlite GitHub Action:

on: [push]


jobs:
  starlite:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4


      # Do your things here: build, test, deploy...


      - name: Run Starlite action (alpha)
        uses: getstarlite/starlite-action@v0
        with:
          api-key: ${{ secrets.STARLITE_API_KEY }}
          org-id: 'demoorg' # Optional: Will be inferred if not provided
          record-id: 'demorecord' # Optional: Will be inferred if not provided

Metrics

Metrics provide insights about activity, performance, and various lead times for a Record. Assuming you set up the event integration, Starlite provides both DORA metrics and more general engineering metrics.

How to handle Metrics

If you use a supported Version Control System (VCS), such as GitHub, then sending events to Starlite is as simple as setting up a guides for several tools are provided below. These webhooks are then run automatically when relevant events occur.

Starlite also supports sending events via the Integration API, in effect supporting any situation, as long as you can produce the correct input and send it over an HTTP request.

Handling deployment metrics

Deployments mark the moment that a successful deployment has been performed. “Successful” in this context means that everything up until that moment (e.g. compilation, tests…) has worked without issues and the code is now available in a production environment. The right moment to send this event is therefore at the very end of a workflow in which a deployment has been performed (assuming there are no events post-deployment).

Some VCS tools provide native support for deployment events:

Wherever these events are supported, Starlite will use them. If you already use e.g. GitHub or GitLab deployments, then Starlite will track those. Note that Starlite, however, will not check the name of the environment or anything like that; it will just track the deployment event itself.

With any other VCS tools you will need to manually fire a deployment event when that happens. Please see the Integration API documentation for more details.

If you are already using the provided integration tools, then you can use them for this purpose. Here’s an example of using the Starlite GitHub Action to emit the deployment event:

on: [push]


jobs:
  starlite:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4


      # Do your magic here: build, test, deploy...


      - name: Run Starlite action (alpha)
        uses: starlite/starlite-action@v0
        with:
          api-key: ${{ secrets.STARLITE_API_KEY }}
          org-id: 'demoorg' # Optional
          record-id: 'demorecord' # Optional
          run-standards: 'false' # Don't do any of the other stuff
          run-record: 'false'    # Don't do any of the other stuff
          run-deployment: 'true' # Fire the deployment event using the Integration API

In the above example we are only firing the deployment event but none of the other ones.

Again, if you cannot use any of the provided tools, or if you want to have a shorter/terser solution, you can always send the event yourself using Starlite’s Integration API.

Handling incident metrics

There is no industry-standard way of handling, labeling, or acting on incidents. This means that Starlite may require certain new conventions on your end to ensure that Starlite can correctly track incidents. We’ve tried to make it very easy and generalized, though!

Incidents have one (then later: two) critical pieces of information:

  1. When they occured.
  2. When they were closed or “resolved” (eventually).

We identify the same incident by an appropriate, fixed and unique ID. This is handled easily when you are integrating from a VCS, since those already have issue IDs.

Here’s how, in practice, opening and closing incidents will look using your tools:

  • Open incident: Create a GitHub Issue with the (custom) incident label.
  • Close incident: Close the Issue or unlabel incident label.

Support for Metrics

Starlite supports several tools for integrating Metrics. We aim to accurately integrate all important events, but sometimes the design of the integrating tool makes this impossible or the event is simply not available.

You can combine tools, for example, if you use a separate issue tracked (such as Jira) and keep code and pull requests in GitHub. However, in that case you will need to ensure that the integrations don’t overlap in terms of events sent to Starlite, so as to create duplicate events.

In the spirit of transparency, we’ve outlined what events we are able to receive from a correct integration for each of the supported tools.

MetricSupported?
Pushed✅
Deployed✅
Commented on issue✅
Commented on PR✅
Issue opened✅
Issue labeled (opened)✅
Issue unlabeled (closed)✅
Issue deleted (closed)✅
Issue resolved (closed)✅
PR opened✅
PR approved✅
PR changes requested✅
PR merged (closed)✅
PR deleted (closed)✅
Merge Time*✅
Review Time*✅
Review Size*✅

* = Derived metric.

Integrating Metrics

Read on for implementation guides for your tool, together with examples.

  1. Navigate to your repository and go to Settings > Webhooks and create a new webhook.
  2. Set https://integration.starlite.systems/event/{YOUR_ORG_ID}/{YOUR_RECORD_ID}/{YOUR_TOKEN} as the URL, updating it with your values.
  3. Set application/json as the content type.
  4. Leave the secret empty.
  5. SSL verification should be enabled.
  6. Click “Let me select individual events” and add the following events:
  • Deployment statuses
  • Issues
  • Issue comments
  • Pushes
  • Pull requests
  • Pull request reviews
  • Pull request review comments

Please see this guide if you need more instructions.

If you want to automate this via their API, you can use:

Terminal window
curl -X POST \
-H "Authorization: token {YOUR_PERSONAL_ACCESS_TOKEN}" \
-H "Accept: application/vnd.github+json" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/repos/{OWNER}/{REPO}/hooks \
-d '{
  "name": "web",
  "config": {
    "url": "https://integration.starlite.systems/event/{YOUR_ORG_ID}/{YOUR_RECORD_ID}/{YOUR_TOKEN}",
    "content_type": "json",
    "insecure_ssl": "0"
  },
  "events": [
    "deployment_status",
    "issues",
    "issue_comment",
    "push",
    "pull_request",
    "pull_request_review",
    "pull_request_review_comment"
  ],
  "active": true
}'