Populating Custom Fields from GitHub

[Richard Simpson]

Howdy!

We've been using our own integration to complement the GitHub integration and it's been working very well! However, I was wondering if there was a recommended pattern we should follow if we wanted to auto-fill Custom Fields using GitHub (or any other service) metadata.

Would it just be like a sort of standard metric where we just upstert the value when receiving a webhook? Is there an appropriate API to use for this?

[Taylor · Accepted solution]

Welcome @Richard Simpson! Awesome to hear you have been running ahead of us and building some additional functionality with our public APIs and they are working well for you. 

If you have any time, would love to quickly hear more about what that additional integration does? Anything we can add to the roadmap to better support future plans?

To your question

To auto-fill custom fields using GitHub (or any other metadata), it's a pretty similar pattern. So, taking a step back - we offer 3 key areas for sending whatever you want in. 

(1) Custom Events -> These are stored against the component and show up on the component activity timeline/list view where you can see activity for a given service and all the upstream dependencies you have on other services and those events all in a single place.. Think a deployment succeeded or failed event. A build failed event. a PR merged event. An incident event, etc.

You can send any event you would like that helps developers understand activity on the component. The main benefit is the Type, Title, and URL so you can click directly into that event - the build, the deployment, the war game being ran, the incident, the feature flag, etc.

This is a screenshot for what it would look like on the Home Page, which just shows a list of components you care about (no dependency information) but conveys what all the events look like. 

API for this is a single rest end point https://developer.atlassian.com/cloud/compass/rest/api-group-events/#api-group-events

(2) Custom Metrics -> These are stored against the component and show up as the metric cards within each individual component. They can also be used with Scorecards to set criteria and thresholds. So, think "PR Cycle Time < 24 hours" based on last 25 PRs or something. We give some of these out of the box with the GitHub integration, as you know, and calculate them based on the events above. 

Again, this is highly extensible is that you can create any arbitrary metric name you want (e.g. "number of coffee cups" or "Open SEV1 vulnerabilities past 28 days"). You can then pass those values in from any source - we do this with Bitbucket, Github, Opsgenie, etc. as the source. We are working towards letting you add trends, see reports across the whole set of components, etc. We have seen customers create lots of these mixed with custom scorecards!

API for this is a single rest point again https://developer.atlassian.com/cloud/compass/rest/api-group-metrics/#api-group-metrics

Here is an excellent guide on the subject end to end: https://developer.atlassian.com/cloud/compass/integrations/create-a-data-provider-app/


Things like this: 

• (3) Custom Fields -> This is similar to how Jira adds custom fields. We only provide 3 types today - text, checkbox, and number, but will add more as we go - so let us know if you would like to see another type!
  
  For this, you can again use the API and create custom fields, apply them to components, and fill out their values. 
  
  For custom fields, this uses our GraphQL APIs as you are updating more info on the component itself and various fields. If you want help writing some of the GraphQL queries, let us know, happy to send over some example snippers to walk all the way through. It would help us improve these as well!
  
  Check out
• https://developer.atlassian.com/cloud/compass/graphql/#mutations_createCustomFieldDefinition to create the new custom field globally.
• And then https://developer.atlassian.com/cloud/compass/graphql/#mutations_updateComponent to update custom fields. 

So, long answer but I hope that broader context may help you as you continue to build out and customise the internal developer experience on Compass. It's hard to stress just how much time we have put into making this product extremely developer friendly and extensible through - both the data model and extending the UI.

Cheers!

[Richard Simpson]

Thank you for the comprehensive answer!

Any snippets for updating a custom field (say from a webhook handler) would be super helpful!

[Josh Campbell]

Hey Richard, here's a GraphQL code snippet that got added to our examples repo yesterday that helps with updating custom field values on a component. Using our Forge SDK you'll want to see these relevant docs for updating metric values from a webtrigger/webhook:

• Start here with the UpdateComponent method which is how you update the metric value, we don't have a separate method just for updating values yet (added as a backlog item!)
• Then checkout the UpdateComponentInput interface
• and finally one of these depending on field type

Hope this helps!

[Richard Simpson]

@Josh Campbell reviewing that API it looks like what I needed! Reviewing the API details, it's not clear if I have to provide all the information in the Input or just what I'm changing (so only `currentComponent` and `customFields` in the custom field case)