Skip to content
Phaset Docs

Integration guide

Phaset 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 Phaset.

Integration overview

Section titled “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 Phaset 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 Phaset supports

Section titled “Which tools Phaset supports”

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

Where do you host your Records and Standards?

Section titled “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.

Phaset supports:

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

Where do you host your issues?

Section titled “Where do you host your issues?”

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

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

Phaset supports:

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

Can I use different tools for code and issues?

Section titled “Can I use different tools for code and issues?”

Yes, that’s entirely possible!

Records and Standards

Section titled “Records and Standards”

Records constitute the central feature of Phaset, supporting your needs around documenting software.

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 Phaset user interface.

How to handle Records and Standards

Section titled “How to handle Records and Standards”

The information displayed in Phaset’s Records can be stored in a structured JSON file: This is called the manifest file and is always named phaset.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 Phaset; 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 Phaset integration. Note that Phaset 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

Section titled “Integrating Records and Standards”

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

  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:
  • PHASET_API_KEY: Your Phaset API key.
  • PHASET_ENDPOINT: Your Phaset endpoint URL (e.g., https://phaset.example.com/integration)
  • PHASET_ORG_ID: (Optional) Your Organization ID. Will be inferred from the organizationId in the manifest file if not explicitly provided.
  • PHASET_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 default to true.
  • RUN_DEPLOYMENT: This defaults to false.

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

Here’s an example of using the Phaset GitHub Action: TODO

on: [push]


jobs:
  phaset:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: Checkout
        uses: actions/checkout@v5


      - name: Run Phaset action (alpha)
        uses: phasetdev/phaset-action@v0
        with:
          endpoint: ${{ secrets.PHASET_ENDPOINT }}
          api-key: ${{ secrets.PHASET_API_KEY }}
          org-id: 'demoorg' # Optional: Will be inferred if not provided
          record-id: 'demorecord' # Optional: Will be inferred if not provided
          #run-deployment: 'true' # Uncomment to fire deployment events

Metrics

Section titled “Metrics”

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

How to handle Metrics

Section titled “How to handle Metrics”

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

Phaset 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

Section titled “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, Phaset will use them. If you already use e.g. GitHub or GitLab deployments, then Phaset will track those. Note that Phaset, 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 Phaset GitHub Action to emit the deployment event:

on: [push]


jobs:
  phaset:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: Checkout
        uses: actions/checkout@v5


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


      - name: Run Phaset action (alpha)
        uses: phasetdev/phaset-action@v0
        with:
          endpoint: ${{ secrets.PHASET_ENDPOINT }}
          api-key: ${{ secrets.PHASET_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 Phaset’s Integration API.

Handling incident metrics

Section titled “Handling incident metrics”

There is no industry-standard way of handling, labeling, or acting on incidents. This means that Phaset may require certain new conventions on your end to ensure that Phaset 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

Section titled “Support for Metrics”

Phaset 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 Phaset, 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

Section titled “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.phaset.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.phaset.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
}'