# What is Rely.io?

[Rely.io](http://rely.io/) is an internal developer portal designed for modern engineering teams. It offers a comprehensive software catalog that centralizes insights about your tech stack.

This catalog centralizes insights about your tech stack and includes maturity and quality scorecards to uphold the highest standards. Additionally, Rely.io enhances these core functions with a variety of self-service options for developers.

Watch a quick **3 minute** overview of the platform with José Velez, CEO and Founder of Rely.io 👇

{% embed url="<https://youtu.be/riXXGDQmAm8>" %}

## How does Rely.io fit into the big picture?

Internal Developer Portals are a small part of the developer lifecycle but an important one, as they centralize insights and processes from several tools into a single location enable a much better developer experience.

Through its strong set of integrations with the most common tools and platforms, Rely.io empowers developers to be more effective on their day-to-day tasks.&#x20;

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2F7JT2RETg6btAeCL2pBK1%2FPitch_asset.png?alt=media&amp;token=a93bd5a5-e74c-4dec-8154-08941e1f8ce2" alt=""><figcaption></figcaption></figure>

### Software Catalog

Navigating your engineering stack can be complex; however, managing it doesn't have to be. The Software Catalog in Rely centralizes crucial data such as service ownership, dependencies, documentation, deployments, observability, and incident management. This feature reduces tool sprawl and simplifies updates.&#x20;

### Software Maturity Scorecards

Elevate your organizational standards with Rely's Scorecards and Leaderboards. Encourage adherence to best practices in production readiness, DORA metrics, and observability by making their adoption competitive and engaging across teams.&#x20;

### Self-Service Actions

Boost developer productivity with Rely’s extensive self-service capabilities. Enable developers to autonomously perform tasks such as scaffolding services or provisioning cloud resources, all within a user-friendly interface. This empowerment leads to faster innovation and a more agile response to changing needs.

### Automation Workflows

Streamline and optimize your engineering operations with Rely’s Automation Workflows. Integrate seamlessly with external data sources through plugins, enhancing your software catalog with real-time updates.&#x20;

Leverage out-of-the-box automation rules to unify entity representation and standardize cross-tool entities, ensuring consistency and clarity across your IDP. As you add more plugins and set up additional automation rules, your catalog becomes richer and more detailed, reducing manual effort and improving accuracy.

## Get started with Rely

Trying out Rely.io is free and simple!

* For a firsthand look at a fully set-up Rely IDP, check out our [public demo](https://demo.rely.io/).
* If you want to create your own account, [simply sign-up](https://webapp.rely.io) and follow our [getting started](/getting-started-guide) guide.


# How Rely.io works

In this page, we’ll do a deep dive over how we built Rely.io’s internal developer portal that helps software companies with distributed architectures deliver high-quality software at scale.

Rely.io’s developer portal is designed for the most complex enterprise environments, therefore it was built with security, scale, and consistency in mind. With features like role-based access control (RBAC), open-source agents that can be self-hosted to integrate with your stack and run self-service actions, encrypted data handling, audit logs, and seamless integration with identity providers like Okta via SAML/SCIM, Rely.io provides everything modern enterprises need.

Below we'll break down how Rely.io works behind the scenes, detailing the data and communication flows between its components and customer environments

***

#### Some context

Every year, **companies waste more than $1 trillion** because **developers spend up to 40% of their time** working on mundane, non-code-producing work.

At[ Rely.io](http://rely.io), our goal is to change that. Our mission is to empower engineering organizations in fostering a service ownership and engineering excellence culture.

We’re building the next generation of intelligent tools and automation to supercharge developer productivity and reduce developer toil.

To achieve this goal,[ Rely.io](http://rely.io) is starting by building an Internal Developer Portal that empowers engineering organizations to enhance visibility and engineering standards across their software ecosystem.

Our goal is to simplify the developer experience while maintaining strong standards of security, autonomy, and flexibility. Our Software Catalog gives developers a holistic understanding of your development lifecycle and underlying architecture. Our Scorecards helps teams define, promote and track the adoption of engineering standards. And, our Self-service Hub empowers developers to move faster while staying in the golden path - baking best practices into developer routines and automating work away with project templates, boilerplate code and automation workflows to provision resources, deploy services or any action they want to standardize across the Software Delivery Lifecycle (SDLC).

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXeG1XgSUqYklKtPXhkjCAiAZV2Ia72uNIBlTgFwHMFZ8UMJ8ucoaicvHq6t2H0X58VOTT3KtU2DqYKscD5QcsohANLngXmUK7E-rij0vSlRWxWiACzZe1Ofh1j04sKEdCnAGLzI6EaqBew7ostt-fZBnQKY?key=3tsFYNxwbEG-GnOvp2QdAw" alt=""><figcaption></figcaption></figure>

***

## Our Architecture

To create a unified and secure platform, we built Rely.io using a mix of managed services and open-source components. This gives users the flexibility to either self-host parts of the system or rely on our managed services.

We have four main components:

1. **SaaS Web Application** – Available at <https://webapp.rely.io>, this user interface allows customers to manage their catalog, scorecards, and self-service actions. It also provides tools for configuring RBAC (role-based access control) and access management tools.
2. **Public API** – A REST API that gives programmatic access to all the key features in Rely.io — catalog management, automations, scorecards, and more.
3. **Galaxy Integration Framework** – An open-source framework that users can install within their cloud environment, keeping all data within their network and avoiding the need to expose APIsy publicly. You can find it at <https://github.com/Rely-io/galaxy-oss>
4. **Self-service Agent** – An open-source agent that users can deploy via Helm or Docker. It runs within their environment, checking for and executing pending actions triggered through Rely.io’s UI or API, without requiring Rely.io to have direct write access to their platforms. You can find it at <https://gitlab.com/relyio/backend/self-service-agent>.

Below is a simplistic illustration of how these components interact with each other and with the customer environments:

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FJET1pPhNVqD1zhq6k3AQ%2Fimage.png?alt=media&amp;token=6d02fd33-2ce4-46b4-a70a-fa9f476c7fbf" alt=""><figcaption><p>Overview of Rely.io Architecture (simplistic view)</p></figcaption></figure>

***

## The core data flows

#### Populating your software catalog with plugins

To get started, you need to install plugins for the core tools in your engineering stack, ensuring that Rely.io integrates smoothly and becomes the single source of truth for your software ecosystems.

We recognize that in regulated industries (like finance), exposing APIs or cloud services to the public can raise compliance concerns. That’s why we created the Galaxy Integration Framework — an open-source framework that runs entirely within your cloud environment.

Galaxy integrates with your tools (e.g., Git, CI/CD, monitoring) by performing periodic requests to gather information, pushing it to Rely.io via secure APIs.

You have two options for installing plugins:

**Self-hosted plugins** – with the Galaxy framework, you can deploy plugins using Docker or Helm in your environment. The Galaxy integration agent runs within your network (e.g., within your VPC) and periodically communicates with your tools’ APIs, transforming and securely transmitting data to Rely.io’s control plane. This approach keeps everything within your infrastructure, with no need to expose anything externally.

**Managed plugins** – if you prefer not to self-host, Rely.io also offers managed plugins hosted within our cloud infrastructure. These plugins authenticate with your tools' APIs (e.g., Datadog) and periodically fetch data over HTTPS to update your software catalog. When possible, Rely.io also sets up webhooks to ensure immediate updates as they happen, minimizing API requests and keeping data available in near real time.

***

#### Running self-service actions

Rely.io’s Self-Service Agent is another key component, built with the same principle of security by design. Self-service actions enable developers to automate routine tasks, such as resource provisioning or service deployment, through either the UI or code definition files.

The agent runs in your environment, giving you full control without needing to grant Rely.io direct access to your tools or infrastructure. Every minute, the agent checks Rely.io’s API for new tasks. When it finds a task, it starts executing it in your environment and continuously reports on the status and progress of the workflow. This keeps you updated in real-time throughout the entire execution process.

Self-service actions can be initiated through the web UI or an API request. Whether self-hosted or managed by Rely.io, the agent handles these actions, interacting with tools like Kubernetes, GitLab, or Jenkins to carry out each step. As the workflow progresses, the agent keeps sending updates back to Rely.io, which are reflected in the portal and notifications.

Just like the Galaxy framework, the Self-Service Agent can be self-hosted or managed by Rely.io, depending on your needs.

***

#### Interacting with the developer portal through the web app

The Rely.io web app is the central hub where platform engineers, SRE teams, and product engineering teams can manage all aspects of their environment. The app provides a user-friendly interface for:

* Managing the software catalog
* Defining and tracking scorecards
* Running, reviewing, and approving self-service actions
* Managing user access and role-based access control (RBAC)

This interface simplifies the experience of interacting with live data, configurations, and actions across the entire software ecosystem.

***

#### GitOps with Rely.io – Entity and configuration definition files

Rely.io is designed to integrate tightly with your existing developer workflows. We introduced entity and code definition files to let you manage everything via code — whether it’s blueprints for services, scorecards for monitoring, or self-service actions.

Today, the way to set this up is to configure a job (provided by Rely.io) in your CI/CD pipeline to push the changes in the entity and configuration code definition files in those repos to our Public API to ensure the changes are reflected in Rely.io when those files are changed in your repo.&#x20;

Soon, we will release a new capability that will allow Rely.io to continuously scrape the repositories you define in your git provider integration, detecting changes to any definition files and updating the system automatically. This ensures that your catalog, scorecards, and workflows are always up-to-date with the latest configurations.

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXd91rkc_FAeqRBF82QEv956MHzd9Oen0Jobhz4PNuRP_UUBwIq3T9Igh33Ez0vxKb2TvsH4VFNaAGK2AngDh4dUkGWj3tx7_Ent1SJ9YGL_8Yr7nqPduqc3SHWbWZ8hlQwPD5k0qATEkex-xTs6wN_crYjm?key=3tsFYNxwbEG-GnOvp2QdAw" alt=""><figcaption><p>Overview of Rely.io's GitOps workflow (simplistic view)</p></figcaption></figure>

***

#### Extending information and managing configurations with the Public API

Every action available through the web interface can also be accessed programmatically through our REST API. Teams can integrate Rely.io’s functionality directly into their existing workflows.

The Rely.io Public API allows you to programmatically push data into the platform, whether to update your catalog or automate workflows.

You can execute all the CRUD operations (Create, read, update, and delete) of all the different entities, blueprints, scorecards and self-service actions configurations within your developer portal.

You generate an API key from Rely.io’s web interface and authenticate your requests using a Bearer token in the API headers.

Your system sends data (e.g., entities, scorecards) via the API, and it is immediately ingested into Rely.io’s backend.

You can also define granularly which assets can suffer changes through the UI, or simply programmatically. For example, in your software catalog, you can define that a given property (e.g. the owner of a service) can’t be changed through the UI, only programmatically. This ensures that Rely only accepts changes to that property through the GitOps workflow or through the Public API.

Then every change in the product is recorded in the audit logs so that you can always audit who changed what, when and you can revert changes if needed.

<br>


# Getting Started Guide

Welcome to [Rely.io](http://rely.io/), your go-to Internal Developer Portal designed to streamline your tech-stack management. This guide will dive you right into action by help you to:

1. [Create an account for your organization](/getting-started-guide/create-an-account-for-your-organization)
2. [Add your first plugin](/getting-started-guide/add-your-first-plugin)
3. [Import services into the Service Catalog](/getting-started-guide/import-services-into-the-service-catalog)
4. [Make the Software Catalog your own](/getting-started-guide/make-the-software-catalog-your-own)

Let’s jump in!


# Create an account for your organization

## Creating an account

Creating an account is the first step to getting started with Rely.io. To do so, navigate to <https://rely.io> and click "Request free trial access"/

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FBzHaUiXkiE4Lan2xM9uB%2FScreenshot%202025-01-30%20at%2016.26.05.png?alt=media&amp;token=9ee64d44-2f35-46cd-84b0-404cb8abe066" alt=""><figcaption></figcaption></figure>

Now, you will be asked to sign up to Rely.io. Here you can choose to provide your **name**,  **email address**, **and company name.**&#x20;

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FwwuE0P5HOqLrNQOcnt6s%2FScreenshot%202025-01-30%20at%2016.29.47.png?alt=media&amp;token=7793c8e7-2e0e-4b10-a67a-705ab6da02b7" alt=""><figcaption></figcaption></figure>

After successful sign up, you will receive an email in your mailbox with instructions on how to get access to your free trial through our guided onboarding experience.

## Signing in for the first time

Once your account is created and successfully activated you can now sign in by going to [https://webapp.rely.io](https://rely.io) (if you haven't been redirected to that page already) and using the credentials you specified during the sign up process.

After you sign in you'll be shown a page asking you for an **organization name**. This is the name we will use to provision your Rely.io organization and where all your users, services, cloud resources and many more will reside.&#x20;

Pick your name and select the *finish* button. This step will only take a few seconds.

{% hint style="info" %}
We recommend that you define your company's name in this step
{% endhint %}

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FYqMDMZrDOCzOmfnTiZYT%2Fimage.png?alt=media&amp;token=b0b590dd-8627-4b3c-b513-953881c25c20" alt=""><figcaption><p>Define organization name in onboarding process</p></figcaption></figure>

As soon your organization is created we need to add you to a team. On the next step, fill in your name and create a team. This step will basically create a new user (you) and a new team where you will be included. Click on the finish button to proceed.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2F7A0IFhWXQJkuujf09KtN%2FExport-1727096133300.gif?alt=media&amp;token=f5fa5964-44fc-4f89-a7c4-6aaaf6aa5f21" alt=""><figcaption><p>Add user to team</p></figcaption></figure>

**And that's it!** You have successfully created your Rely.io account. Move on to the next step to [add your first plugin](/getting-started-guide/add-your-first-plugin) and start your Rely.io journey.


# Add your first plugin

Let's kickstart your [Rely.io](http://Rely.io) journey by populating your software catalog. With our plugins, you can seamlessly import services, cloud resources, and much more into your developer portal.

## **Create your first plugin**

Navigate to the [Plugins Page](https://webapp.rely.io/data-model/datasources) by clicking the **Portal Builder** menu on the bottom left and then select **Plugins.** \
\
Initially, you'll see our built-in plugins for the [Rely.io](http://Rely.io) API and the Self-Service Agent. These are designed for managing entities programmatically and execute Self-Service actions.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FsoffPayZXN2PQeuavxyn%2Fimage.png?alt=media&amp;token=d7ba2661-363f-42ae-b4a4-30c6b4588fb6" alt=""><figcaption></figcaption></figure>

To create your first plugin click on **Add Data Source** and select from the available options.&#x20;

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FLMKvXg7DkDllnmbKLw6C%2FScreenshot%202025-01-30%20at%2016.15.02.png?alt=media&amp;token=b5af825d-1e37-46e0-bd5a-1bc90208d321" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Starting with your Git provider (Github, GitLab or Bitbucket) is recommended, as it populates your [service catalog](https://webapp.rely.io/software-catalog/service/list) efficiently - but it is not the only option.&#x20;

Still, for the purpose of this *getting started* guide we will use GitLab.
{% endhint %}

To complete the setup for the selected plugin you need to fill-in the mandatory fields. These change depending on the plugin. Follow the installation steps.&#x20;

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2F9PLdt8X3WvbaSS61A3o7%2Fimage.png?alt=media&amp;token=47328aff-05a4-40ea-ad51-2f97ede07628" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
During this process, you may be redirected to the plugin platform for authorization or asked to input an access token, depending on the plugin.&#x20;
{% endhint %}

After that, select the assets you wish to import (such as repositories or issues) and click the **Submit** button.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FMKPBdf1BpRVrbWzB7uwu%2Fimage.png?alt=media&amp;token=e8fd4873-7c99-4588-991a-4515840de83d" alt=""><figcaption></figcaption></figure>

**And that's it!** The initial discovery run can take a few minutes to complete. As you await the results, this is the perfect opportunity to dive deeper into how you can utilize the data that plugins provide, by exploring the core features of the software catalog.

If you are curious about what happens *under-the-hood* when you add new plugins check out "[*What happens when you install a plugin?*](/plugins-and-automation/what-happens-when-you-install-a-plugin#behind-the-scenes)*"*.

Next, we'll [import services into the service catalog](/getting-started-guide/import-services-into-the-service-catalog).


# Import services into the Service Catalog

In the last step you have created your very first plugin and you were expecting to see some services already in the Service Catalog, right? Don't worry they haven't gone anywhere, we just made so that you are always in control in our Discovery feature.

## Service Discovery

Service Discovery is a process internal to Rely.io that imports the supported information from all the different plugins you have configured in your Rely.io organization.

After you configured your Git provider, Rely.io has effectively started the import process but in order to avoid filling your service catalog with irrelevant or outdated information - *yes, we are developers too and we know how much we like to create repositories for demos and experiments.* We don't need to bring those to your Service Catalog.

## Handling service discovery

On the *Discovery* page you will be shown a list of all the services that were discovered in the configured Git provider. Here you will need to select the services you would like to import and the ones you want to ignore.

To do so, simply go to "*Discovery*" under the "*Portal* *Builder*" menu option and make your selection.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2F6VCTvvX0VchvCt5gkxMs%2Fdiscovery-steps.gif?alt=media&amp;token=c33cd25d-c28a-48aa-bd4b-e9a687f4a370" alt=""><figcaption><p>importing services in Discovery</p></figcaption></figure>

Once you are done you should see a list of the services you added in your [Service Catalog](https://webapp.rely.io/software-catalog/service/list).

{% hint style="info" %}
If for some reason you still don't see you entities or recommendations please ask for support on the in-app chat or send an email to <support@rely.io>.
{% endhint %}

On the next, and last step, let's explore how you can access and [customize your Software Catalog](/getting-started-guide/make-the-software-catalog-your-own).


# Make the Software Catalog your own

## What is the Software Catalog?

The Software Catalog in Rely.io serves as the central hub for all entities within your organization's tech ecosystem, providing an organized overview of software assets, systems, services, and more.&#x20;

The software catalog provides default views for the integrations that you setup but it's extensible so you can make it work for your organization.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2F8fCsAiivPuNw2ZWMrzEB%2Fsoftware-catalog.gif?alt=media&amp;token=ae4f8788-dfc2-4241-bf38-0c0768219b04" alt=""><figcaption><p>Software and Service Catalog overview</p></figcaption></figure>

Entities in the catalog are defined by their properties and relations. These entities are structured through customizable blueprints, enabling tailored access to information and management of the software ecosystem.

## Navigation

Each unique entity type (or blueprint) has its catalog, composed of a list of entities of that type. You can access these catalogs through the side panel in the “Software Catalog” section. Customize your sidebar by pinning or hiding entity types according to your preference.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FFDSL2dqQlViYDIGaEhde%2Fsoftware-catalog-entity-menu-config.gif?alt=media&amp;token=73ceb2a5-1f70-48bd-865f-9e14aac447c9" alt=""><figcaption><p>Customizing Software Catalog Navigation</p></figcaption></figure>

Click “Services” to access your [service catalog](https://webapp.rely.io/software-catalog/service/list). In this view, you can scroll sideways to explore the metadata, properties, and relations fields available for your services.&#x20;

Customize your view by hiding certain columns, changing their order, grouping by, or sorting by a particular field, and then save your customized view for future reference. Clicking on a specific row allows you to access a particular service's entity page for further insight.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FCSk88P6g3yIlfe1zMc2i%2Fservice-directory.gif?alt=media&amp;token=6f58cfd1-ef73-49d5-a97c-185fa83a2d02" alt=""><figcaption><p>Service Catalog Details</p></figcaption></figure>

A cool thing about the service catalog is that you don't even need to open the service details page to interact with charts or navigate to external dependency pages. You can do it directly from the service list.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FBYxtyl04srdh3Gz1qrxL%2Fservice-list-click-widget.gif?alt=media&amp;token=408bacf9-3690-47f3-b77e-663b668d3f6f" alt=""><figcaption><p>View information on Service Catalog list</p></figcaption></figure>

This step covers the basics on how to work with Rely.io. Continue to the next page for more information on [what you could do next](/getting-started-guide/whats-next).


# What's Next?

Congratulations! You've just completed the getting started guide for [Rely.io](http://Rely.io). Your journey is only beginning, so feel free to:

* [Install additional plugins](https://docs.rely.io/plugins-and-automation/plugin-instalation-guides) to expand your software catalog's coverage.
* [Invite colleagues](/invite-users) to join the platform.
* [Tailor the properties and relations](/software-catalog/usage-guide/updating-a-blueprint) for each entity type by modifying your data model.
* [Add custom dashboards](/home-pages) that are relevant to your team (docs)


# Basic Concepts


# Entities

At the core of [Rely.io](http://rely.io/) is its software catalog. Each entity within this catalog can be represented as a JSON file, which we refer to as an [entity descriptor](#entity-descriptor).

## Entity ID

Throughout our documentation, you'll encounter references to the "entity ID." This unique identifier is essential in [Rely.io](http://Rely.io) for establishing relationships between entities and retrieving information. It's crucial to note that the entity ID must be **globally unique across all entities**.

{% hint style="info" %}
An entity ID is usually the very first field in the [entity's descriptor](#entity-descriptor).
{% endhint %}

## Entity Descriptor

Regardless of whether you're using UI editing or GitOps to manage your entities, the definitions are backed by JSON files. Each file is a fully compliant OpenAPI 3 spec file, with our own specific extensions.

{% hint style="info" %}
**You can still use Rely even if you don't use OpenAPI/Swagger.**

We use the OpenAPI specification as a foundation for entity and blueprint data. Since it's an open standard with official support for extensions, we can expand it to serve as an entity or blueprint descriptor specification. This approach allows for optional use of actual OpenAPI fields.
{% endhint %}

All entities have three other metadata fields besides the [entity id](#entity-id):

* **Name:** A user-friendly display name.
* **Blueprint ID:** A reference to the entity's type.
* **Description** (Optional): A concise overview of the entity for further context.

An entity descriptor also contains all relevant data that makes up the entity itself which might envolve:

* **Properties:** The defining characteristics and attributes of an entity.
* **Relations:** These indicate how the entity is connected to or interacts with other entities within Rely.
* **Sources:** These specify where the entity's data originates from in the case of automated integrations with external systems via Rely's plugins.

## Example Service Entity

```json
{
  "id": "advertising",
  "blueprintId": "service",
  "title": "Advertising",
  "description": "A Helm chart for deploying a Python app for advertising purposes",
  "properties": {
    "tier": "Customer Facing",
    "readme": "https://github.com/rely.io/demo-ads/-/blob/master/README.md?ref_type=heads",
    "on-call": "tim-cook@gmail.com",
    "version": "0.1.5",
    "language": "Python",
    "lifecycle": "Production",
    "repo-link": "https://github.com/rely/ads",
    "code-owners": [
      "elon-musk@gmail.com",
      "bill-gates@gmail.com",
      "daniel-ek@gmail.com",
      "sheryl-sandberg@gmail.com",
      "reed-hastings@gmail.com"
    ],
    "handles-pii": false,
    "monitor-links": [
      "https://grafana.com",
      "https://prometheus.com",
      "https://datadog.com"
    ],
    "quality_gate_status": "Passed",
    "unit-tests-coverage": 87,
    "communication-method": "GraphQL"
  },
  "relations": {
    "team": {
      "value": "marketing-and-advertising-team"
    },
    "internal-dependencies": {
      "value": [
        "anomaly-detector",
        "load-generator",
        "purchase-processor"
      ]
    },
    "running-instances": {
      "value": [
        "ads-staging",
        "ads-security",
        "ads-dev",
        "ads-sandbox",
        "ads-production"
      ]
    },
    "GitlabRepository": {
      "value": "adversiting"
    },
  },
  "sources": {
    "automation.rely.gitlab.v1.repository-to-service.gitlab.v1.repository.adversiting": {
      "type": "automation",
      "config": {
        "automationId": "rely.gitlab.v1.repository-to-service",
        "blueprintId": "gitlab.v1.repository",
        "entityId": "adversiting",
        "fields": [
          "title",
          "description",
          "properties/readme",
          "properties/language",
          "properties/repo-link",
          "relations/GitlabRepository"
        ]
      },
      "activeMappings": {
        "title": null,
        "description": null,
        "properties/readme": null,
        "properties/language": null,
        "properties/repo-link": null,
        "relations/GitlabRepository": null
      }
    },
}
```

## Learn More

<table data-view="cards"><thead><tr><th>Entity Actions</th></tr></thead><tbody><tr><td><a href="/software-catalog/usage-guide/creating-a-new-entity">Creating a new Entity</a></td></tr><tr><td><a href="/software-catalog/usage-guide/updating-an-entity">Updating an Entity</a></td></tr><tr><td><a href="/software-catalog/usage-guide/tracking-entity-changes">Tracking Entity Changes</a></td></tr><tr><td><a href="/software-catalog/usage-guide/customizing-an-entitys-page">Customizing an Entity's page</a></td></tr></tbody></table>


# Blueprints

Every entity in Rely is associated with a blueprint that defines the entity's type. Like entities, every blueprint can be represented as a JSON file called a [blueprint descriptor](#blueprint-descriptor).

In [Rely.io](http://Rely.io), blueprints are schemas that outline the structure and attributes of entities such as services or resources. They provide a customizable framework for documenting and managing your software ecosystem, while entities serve as specific instances within this framework.

## Blueprint ID

&#x20;The blueprint ID is a unique identifier that's used throughout Rely.io to declare dependencies to other blueprints or look-up information. The blueprint ID must be **globally unique across all blueprints**.

{% hint style="info" %}
An blueprint ID is usually the very first field in the JSON representation of a Rely.io blueprint.
{% endhint %}

## Blueprint Descriptor

Regardless of whether you're using UI editing or GitOps to manage your blueprints, the definitions are backed by JSON files that's a fully compliant OpenAPI 3 spec file, with our own specific extensions.

{% hint style="info" %}
**You can still use Rely even if you don't use OpenAPI/Swagger.**

We use the OpenAPI specification as a base for entity and blueprint data, since it's an open spec with official support for extensions. That lets us extend it to be an entity or blueprint descriptor spec with optional usage of actual OpenAPI fields.
{% endhint %}

All blueprints have two other metadata fields besides the [blueprint id](#blueprint-id):

* **Name:** A user-friendly display name.
* **Description** (Optional): A concise overview of the blueprint for further context.

A blueprint descriptor also contains all relevant data that makes up the entity itself which might envolve:

* **Properties:** These indicate the [type of data ](/basic-concepts/property-data-types)that properties in entities created from this blueprint can hold. Properties have an id, title and description of their own.
* **Relations:** These indicate how entities created from this blueprint can be connected with other entities in Rely. Relations have an id, title and description of their own as well as a target blueprint. Relations can be both 1:1 or 1:many.

## Example Service Blueprint

```json
{
  "id": "service",
  "title": "Service",
  "description": "Representation of a service ",
  "icon": "terminal",
  "schemaProperties": {
    "type": "object",
    "properties": {
      "handles-pii": {
        "type": "boolean",
        "title": "Handles PII",
        "description": ""
      },
      "unit-tests-coverage": {
        "type": "number",
        "title": "Unit Tests Coverage",
        "description": ""
      },
      "helm-version": {
        "type": "string",
        "title": "Helm Chart Version",
        "description": ""
      },
      "lifecycle": {
        "enum": [
          "Production",
          "Experimental",
          "Deprecated"
        ],
        "type": "string",
        "title": "Lifecycle",
        "description": ""
      },
      "github-url": {
        "type": "string",
        "title": "Repo URL",
        "format": "url",
        "description": ""
      },
      "code-owners": {
        "type": "array",
        "title": "Code Owners",
        "items": {
          "type": "string"
        },
        "description": ""
      },
      "helmchartyaml": {
        "type": "string",
        "title": "Helm Chart",
        "format": "yaml",
        "description": ""
      },
      "readme-content": {
        "type": "string",
        "title": "README ",
        "format": "markdown",
        "description": ""
      }
    }
  },
  "relations": {
    "team": {
      "array": false,
      "title": "Team",
      "value": "team",
      "description": ""
    },
    "internal-dependencies": {
      "array": true,
      "title": "Dependencies",
      "value": "service",
      "description": ""
    },
    "running-instances": {
      "array": true,
      "title": "Running Instances",
      "value": "running-service",
      "description": ""
    }
  },
  "referenceProperties": {},
  "options": {
    "showInSideBar": true
  }
}
```

## Learn More

<table data-view="cards"><thead><tr><th>Blueprint Actions</th></tr></thead><tbody><tr><td><a href="/software-catalog/usage-guide/creating-a-new-blueprint-and-catalog">Creating a new Blueprint</a></td></tr><tr><td><a href="/software-catalog/usage-guide/updating-a-blueprint">Updating a Blueprint</a></td></tr><tr><td><a href="/software-catalog/usage-guide/tracking-blueprint-changes">Tracking Blueprint Changes</a></td></tr></tbody></table>


# Property Data Types

Properties are configured within [blueprint descriptors](/basic-concepts/blueprints#blueprint-descriptor). This is where you'll find and manage a property's id, title, descriptions and data type.

{% hint style="info" %}
Property IDs need to be unique within a single blueprint, but properties in different blueprints can have similar IDs.
{% endhint %}

The data type specified in the [blueprint descriptor ](/basic-concepts/blueprints#blueprint-descriptor)determines the kind of data that the property can store within an [entity descriptor](/basic-concepts/entities#entity-descriptor). This affects how data is interpreted and displayed within Rely.&#x20;

{% hint style="info" %}
A property’s data-type in a blueprint is defined by a combination of two parameters: `type` and `format`.&#x20;
{% endhint %}

{% hint style="warning" %}
The data type of a property determines the operators available for configuring [scorecard](/basic-concepts/scorecards) and [automation](/basic-concepts/actions-and-automations/automation-rules) rules.
{% endhint %}

Below, we provide an overview of all the available data types, exploring their utility and how to configure them.

### String

Strings represent text data. They are versatile and can include mostly anything from namespaces, statuses, etc.

<details>

<summary>How a "string" property looks like a  <a href="/basic-concepts/blueprints#blueprint-descriptor">blueprint descriptor</a>.</summary>

```json
{
  // Blueprint metadata
  ...
  // Blueprint Properties
  "schemaProperties": {
    "type": "object",
    "properties": {
      // My string property
      "my-property-id": {
        "type": "string",
        "format": null
        "title": "My Property Title",
        "description": "..."
      }
}
```

</details>

### Number

Numbers are used for numerical data, from quantities to identifiers.

<details>

<summary>How a "number" property looks like in a <a href="/basic-concepts/blueprints#blueprint-descriptor">blueprint descriptor</a>.</summary>

```json
{
  // Blueprint metadata
  ...
  // Blueprint Properties
  "schemaProperties": {
    "type": "object",
    "properties": {
      // My number property
      "my-number-property": {
        "type": "number",
        "format": null,
        "title": "My Number Property",
        "description": "A numeric property."
      }
    }
  }
}

```

</details>

### Date-Time

This type is used for date values, ensuring events are accurately timestamped.

<details>

<summary>How a "date-time" property looks like in a <a href="/basic-concepts/blueprints#blueprint-descriptor">blueprint descriptor</a>.</summary>

```json
{
  // Blueprint metadata
  ...
  // Blueprint Properties
  "schemaProperties": {
    "type": "object",
    "properties": {
      // My date-time property
      "my-datetime-property": {
        "type": "string",
        "format": "date-time",
        "title": "My DateTime Property",
        "description": "A property for date and time."
      }
    }
  }
}

```

</details>

### Boolean

Booleans represent binary choices, such as true/false or yes/no scenarios.

<details>

<summary>How a "boolean" looks like in a <a href="/basic-concepts/blueprints#blueprint-descriptor">blueprint descriptor</a>.</summary>

```json
{
  // Blueprint metadata
  ...
  // Blueprint Properties
  "schemaProperties": {
    "type": "object",
    "properties": {
      // My boolean property
      "my-boolean-property": {
        "type": "boolean",
        "format": null,
        "title": "My Boolean Property",
        "description": "A true or false property."
      }
    }
  }
}

```

</details>

### URL

URLs are used to store web addresses, linking to external resources.  Here's some general considerations to keep in mind:

* **Validation:** When assigning values to URL properties, only valid URLs will be accepted. This ensures that the links are functional and lead to actual resources.
* **Display Simplification:** To maintain clarity and prevent clutter in the web application, Rely.io simplifies the display of URLs. Instead of showing the full URL, which can be lengthy and cumbersome, only the domain name is displayed. This approach keeps the interface clean and focused, without sacrificing access to the full URL.

<details>

<summary>How a "URL" property looks like in a  <a href="/basic-concepts/blueprints#blueprint-descriptor">blueprint descriptor</a>.</summary>

```json
{
  // Blueprint metadata
  ...
  // Blueprint Properties
  "schemaProperties": {
    "type": "object",
    "properties": {
      // My URL property
      "my-url-property": {
        "type": "string",
        "format": "url",
        "title": "My URL Property",
        "description": "A property for web addresses."
      }
    }
  }
}

```

</details>

### JSON

JSON properties in Rely offer a flexible solution for storing unstructured data. These properties accept JSON payloads without the need for a predefined schema, accommodating a wide range of data representations.&#x20;

The payload for JSON properties is sanitised upon storage to ensure security and integrity, allowing for a versatile and "everything goes" approach to data storage - as long as it's a valid JSON.

<details>

<summary>How a "json" property looks like in a <a href="/basic-concepts/blueprints#blueprint-descriptor">blueprint descriptor</a>.</summary>

```json
{
  // Blueprint metadata
  ...
  // Blueprint Properties
  "schemaProperties": {
    "type": "object",
    "properties": {
      // My JSON property
      "my-json-property": {
        "type": "string",
        "format": "json",
        "title": "My JSON Property",
        "description": "A property for JSON data."
      }
    }
  }
}

```

</details>

### Object

Object properties in Rely are designed for structured data storage, enabling the representation of complex, nested information structures. These properties require users to define a clear schema beforehand, which outlines the specific structure and type of data that the object will hold.&#x20;

This pre-specification of schema ensures that any data stored in or updated to an object property strictly adheres to the defined structure, maintaining data integrity and consistency across your entities.

<details>

<summary>How an "object" property looks like in a <a href="/basic-concepts/blueprints#blueprint-descriptor">blueprint descriptor</a>.</summary>

```json
{
  // Blueprint metadata
  ...
  // Blueprint Properties
   "schemaProperties":{
      "type":"object",
      "properties":{
          // My Object property
         "my-object-property":{
            "type":"object",
            "format":null,
            "title":"My Object Property",
            "description":"...",
            // My Object Schema 
            "properties":{
               "first-shcmea-prop":{
                  "type":"string",
                  "title":"My First Prop",
                  "description":""
               },
               "second-schema-prop":{
                  "type":"object",
                  "title":"My Second Prop",
                  "description":"...",
                  "properties":{
                     "nested-prop":{
                        "type":"string",
                        "title":"A nested prop",
                        "description":"..."
                     }
                  }
               }
            }
         }
      }
   }
}
```

</details>

### YAML

YAML is ideal for configuration data, favoured for its readability. &#x20;

The payload for such properties is sanitised upon storage to ensure security and integrity, allowing for a versatile and "everything goes" approach to data storage - as long as it's a valid YAML.

<details>

<summary>How a "yaml" property looks like in a <a href="/basic-concepts/blueprints#blueprint-descriptor">blueprint descriptor</a>.</summary>

```json
{
  // Blueprint metadata
  ...
  // Blueprint Properties
  "schemaProperties": {
    "type": "object",
    "properties": {
      // My YAML property
      "my-yaml-property": {
        "type": "string",
        "format": "yaml",
        "title": "My YAML Property",
        "description": "A property for YAML data."
      }
    }
  }
}

```

</details>

### Markdown

Markdown properties are used for text that includes formatting, such as documentation or notes.&#x20;

The payload for such properties is sanitised upon storage to ensure security and integrity, allowing for a versatile and "everything goes" approach to data storage.

<details>

<summary>How a "markdown" property looks like in a <a href="/basic-concepts/blueprints#blueprint-descriptor">blueprint descriptor</a>.</summary>

```json
{
  // Blueprint metadata
  ...
  // Blueprint Properties
  "schemaProperties": {
    "type": "object",
    "properties": {
      // My markdown property
      "my-markdown-property": {
        "type": "string",
        "format": "markdown",
        "title": "My Markdown Property",
        "description": "A property for Markdown text."
      }
    }
  }
}

```

</details>

### OpenAPI

OpenAPI properties should be set to a URL pointing to a valid OpenAPI JSON schema. The display will render the API specification as Swagger documentation.

<details>

<summary>How an "OpenAPI" property looks like in a <a href="/basic-concepts/blueprints#blueprint-descriptor">blueprint descriptor</a>.</summary>

```json
{
  // Blueprint metadata
  ...
  // Blueprint Properties
  "schemaProperties": {
    "type": "object",
    "properties": {
      // My OpenAPI property
      "my-openapi-property": {
        "type": "string",
        "format": "url/openApi",
        "title": "My OpenAPI Property",
        "description": "A URL to an OpenAPI specification."
      }
    }
  }
}

```

</details>

### Iframe

Iframe properties need to be set to URL pointing to a webpage. The display will render the webpage itself, embedding it directly within Rely.

<details>

<summary>How an "iframe" property looks like in a <a href="/basic-concepts/blueprints#blueprint-descriptor">blueprint descriptor</a>.</summary>

```json
{
  // Blueprint metadata
  ...
  // Blueprint Properties
  "schemaProperties": {
    "type": "object",
    "properties": {
      // My iframe property
      "my-iframe-property": {
        "type": "string",
        "format": "url/iframe",
        "title": "My Iframe Property",
        "description": "A URL to a webpage for iframe embedding."
      }
    }
  }
}

```

</details>

### Array

Arrays are used to store lists of values, which can be of any basic data type.

<details>

<summary>How an "array" property looks like in a <a href="/basic-concepts/blueprints#blueprint-descriptor">blueprint descriptor</a>.</summary>

```json
{
  // Blueprint metadata
  ...
  // Blueprint Properties
  "schemaProperties": {
    "type": "object",
    "properties": {
      // My array property
      "my-array-property": {
        "type": "array",
        "format": null,
        "title": "My Array Property",
        "description": "..."
      }
    }
  }
}

```

</details>

### Time Series Query

Time Series Query properties allow you to set up queries for retrieving metrics from external tools through plugin integrations. Data retrieval happens at scheduled intervals, but can also update immediately when visiting a specific entity page with time-series properties.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2F0IwTqL9cIJfYTkeT6pA2%2Fimage.png?alt=media&amp;token=eb32ead9-4da0-4e83-83fb-0d153de806b4" alt="" width="206"><figcaption><p>Time Series Property Display</p></figcaption></figure>

To use this feature, you need compatible plugins (such as Grafana Cloud) installed. Once you've selected a plugin, you can create your query using the querying language provided by the plugin's data source. For example, you can use Grafana's querying language to import metrics directly into your software catalog (see the [Grafana documentation](https://grafana.com/docs/grafana-cloud/developer-resources/api-reference/http-api/data_source/#query-a-data-source) for more details).

Before submitting, [Rely.io](http://Rely.io) runs the query in real-time to check its functionality and ensure it produces data in the correct format.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2Fb3xuFnKXD51jwogWhZ6J%2Fimage.png?alt=media&amp;token=df9e8c10-bafe-458f-81a7-ad68007edd04" alt="" width="375"><figcaption><p>Time Series Creation Form</p></figcaption></figure>

{% hint style="warning" %}
It is recommended that you define these property types via the UI.
{% endhint %}

### Single Value Query

Similar to Time Series Query properties, Single Value Query properties fetch specific data points from external tools via plugin integrations. The key difference is in the expected result: Single Value Queries return a single data point, rather than a series of data points over time.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FycpZhat3dsVOBvhLD1X7%2Fimage.png?alt=media&amp;token=045bd967-e83a-43af-aa9d-8a41915bb3a0" alt="" width="207"><figcaption></figcaption></figure>

To use this feature, you need compatible plugins (such as Grafana Cloud) installed. After choosing a plugin, you can create your query using the plugin's data source querying language. For example, you can use Grafana's querying language to import metrics directly into your software catalog. (For more details, see the [Grafana documentation](https://grafana.com/docs/grafana-cloud/developer-resources/api-reference/http-api/data_source/#query-a-data-source).)

Before submitting, [Rely.io](http://Rely.io) runs the query in real-time to check its functionality and ensure it produces data in the correct format.

{% hint style="warning" %}
It is recommended that you define these property types via the UI.
{% endhint %}

### Reference Properties

A reference property allows you to mirror properties from related entities. When two blueprints have a relationship, a new set of properties becomes available to entities in the "source" blueprint.

## Learn More

<table data-view="cards"><thead><tr><th>Property Actions</th></tr></thead><tbody><tr><td><a href="/software-catalog/usage-guide/updating-a-blueprint">Updating a Blueprint</a></td></tr><tr><td><a href="/software-catalog/usage-guide/updating-an-entity">Updating an Entity</a></td></tr><tr><td><a href="/software-catalog/usage-guide/customizing-an-entitys-page">Customizing an Entity's page</a></td></tr></tbody></table>


# Catalogs

Catalogs are table views that allow you to easily track and explore information about your entities. Each [blueprint](/basic-concepts/blueprints) has a dedicated catalog that lists all entities of that type (e.g., the service catalog, the resource catalog, etc.).

You can access each individual catalog through the side panel entry in the Software Catalog—a term referring to the collection of all your catalogs.

{% hint style="info" %}
You can tailor your Software Catalog to your specific needs by pinning or hiding blueprints in the sidebar, allowing for quick access to frequently used catalogs and minimising clutter.
{% endhint %}

In each catalog, columns can represent a metadata field, a property, or a relationship defined in the blueprint and thus common to all the entities listed.

Catalogs offer customisation options to enhance your navigation and data management experience. You can:

* Choose which columns to display
* Re-order columns&#x20;
* Group entities by one or more specific fields
* Sort data by any field
* Apply text filters

{% hint style="info" %}
&#x20;You can save your view configurations so they become the new standard for a specific catalog **to all users within your organization**.
{% endhint %}

## Learn More

<table data-view="cards"><thead><tr><th>Catalog Actions</th></tr></thead><tbody><tr><td><a href="/software-catalog/usage-guide/creating-a-new-blueprint-and-catalog">Creating a new Catalog</a></td></tr><tr><td><a href="/software-catalog/usage-guide/customizing-a-catalog">Customising a Catalog</a></td></tr></tbody></table>


# Data Model

Your Data Model is the structure formed by all the blueprints defined in your [Rely.io](http://Rely.io) account. It encompasses their properties and the relationships between them.

This model encapsulates the entire schema of how data is organized and interconnected within your system. It also determines all the available data that can be stored across your [Software Catalog](/software-catalog).

## Default Data Model

Rely.io provides an out-of-the-box data model based on common use-cases, but you are free to tailor it to your specific needs and expand it by creating new blueprints or editing existing ones.

{% hint style="info" %}
One of the most common ways of expanding your data model is by installing plugins. Each [plugin has its own specific self-contained data model](/basic-concepts/user-blueprints-vs-plugin-blueprints) that will be added and integrated into your own upon plugin installation.&#x20;
{% endhint %}

{% hint style="warning" %}
The out-of-the-box [scorecards](/basic-concepts/scorecards), [automation rules](/basic-concepts/actions-and-automations/automation-rules) and dashboards were designed with the default data model in mind. \
\
Deleting core default blueprints (such as service, resource, or team) or their properties may require adjusting other default settings later to accommodate these changes.
{% endhint %}

Below, we provide an overview of all the core default blueprints as well as its [descriptors](/basic-concepts/blueprints#blueprint-descriptor).

### Team

The Team blueprint represents groups within an organization, highlighting the roles of members and leaders. It includes properties like leader, members, on-call responsibilities, and communication channels.

<details>

<summary>Blueprint Descriptor</summary>

```json
{
  "id": "team",
  "title": "Team",
  "description": "",
  "icon": "person",
  "schemaProperties": {
    "type": "object",
    "properties": {
      "leader": {
        "type": "string",
        "title": "Leader",
        "description": ""
      },
      "members": {
        "type": "array",
        "title": "Members",
        "description": ""
      },
      "on-call": {
        "type": "string",
        "title": "On-call",
        "description": ""
      },
      "communication-channel": {
        "type": "string",
        "title": "Communication Channel",
        "format": "url",
        "description": ""
      }
    }
  },
  "relations": {},
  "referenceProperties": {},
  "options": {
    "showInSideBar": true,
    "propertiesGroups": {}
  }
}
```

</details>

### Service

The Service blueprint defines an individual service within your software ecosystem, such as a micro-service. It includes properties related to the service's type, lifecycle, programming language, and various communication methods. Key relations include links to the teams responsible for the service and dependencies on other services, underlining its integration within the broader software architecture.

<details>

<summary>Blueprint Descriptor</summary>

```json
{
  "id": "service",
  "title": "Service",
  "description": "Defines a service in your software ecosystem.",
  "icon": "terminal",
  "schemaProperties": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "title": "Type",
        "description": "Type of the service"
      },
      "readme": {
        "type": "string",
        "title": "README",
        "format": "markdown",
        "description": ""
      },
      "language": {
        "type": "string",
        "title": "Language",
        "description": "The code language the service is written in"
      },
      "lifecycle": {
        "enum": [
          "Production",
          "Experimental",
          "Deprecated"
        ],
        "type": "string",
        "title": "Lifecycle",
        "description": ""
      },
      "repo-link": {
        "type": "string",
        "title": "Repository Link",
        "format": "url",
        "description": ""
      },
      "helm-chart": {
        "type": "string",
        "title": "Helm Chart",
        "format": "yaml",
        "description": ""
      },
      "description": {
        "type": "string",
        "title": "Description",
        "description": "A brief description of the service."
      },
      "open-api-schema": {
        "type": "string",
        "title": "OpenAPI Schema",
        "format": "url/openApi",
        "description": ""
      },
      "communication-method": {
        "enum": [
          "REST API",
          "GraphQL",
          "gRPC",
          "Message Queue",
          "WebSocket"
        ],
        "type": "string",
        "title": "Communication Method",
        "description": ""
      },
      "communication-channel": {
        "type": "string",
        "title": "Communication Channel",
        "format": "url",
        "description": ""
      },
      "observability-dashboard": {
        "type": "string",
        "title": "Logs",
        "format": "url",
        "description": ""
      }
    }
  },
  "relations": {
    "team": {
      "array": false,
      "title": "Team",
      "value": "team",
      "description": "The teams that operate this service."
    },
    "dependencies": {
      "array": true,
      "title": "Dependencies",
      "value": "service",
      "description": "Other services that this service relies on."
    }
  },
  "referenceProperties": {},
  "options": {
    "showInSideBar": true,
    "propertiesGroups": {}
  }
}
```

</details>

### Resource

This blueprint is focused on physical or virtual resources, such as cloud infrastructure components. It includes details like resource type, location, and specific cloud service identifiers.&#x20;

<details>

<summary>Blueprint Descriptor</summary>

```json
{
  "id": "resource",
  "title": "Resource",
  "description": "Defines a cloud or infrastructure resource",
  "icon": "storage",
  "schemaProperties": {
    "type": "object",
    "properties": {
      "arn": {
        "type": "string",
        "title": "ARN",
        "description": ""
      },
      "cloud": {
        "enum": [
          "GCP",
          "AWS",
          "Azure"
        ],
        "type": "string",
        "title": "Cloud",
        "description": ""
      },
      "region": {
        "type": "string",
        "title": "Region",
        "description": ""
      },
      "iac-code": {
        "type": "string",
        "title": "IaC Code",
        "format": "yaml",
        "description": ""
      },
      "dashboard": {
        "type": "string",
        "title": "Dashboard",
        "format": "url",
        "description": "the link to the cloud resource"
      },
      "iac-format": {
        "enum": [
          "Pulumi",
          "Crossplane",
          "Terraform"
        ],
        "type": "string",
        "title": "IaC Format",
        "description": ""
      },
      "health-status": {
        "type": "string",
        "title": "Health Status",
        "description": ""
      },
      "resource-type": {
        "enum": [
          "EC2",
          "S3",
          "Lambda",
          "IAM",
          "VPC",
          "Route 53",
          "RDS",
          "SNS",
          "SQS",
          "API Gateway",
          "CloudFormation",
          "Elastic Beanstalk",
          "Elastic Load Balancer",
          "MongoDB",
          "Compute Instance",
          "Compute Disk",
          "Cloud Storage",
          "Cloud Function",
          "Cloud SQL",
          "Stackdriver",
          "VPC Network",
          "Cloud DNS",
          "Postgres",
          "Redis Instance",
          "GKE Cluster",
          "Storage Bucket",
          "Kubernetes Cluster",
          "Kubernetes Pod",
          "Kubernetes Node"
        ],
        "type": "string",
        "title": "Resource Type",
        "description": ""
      },
      "dashboardPageUrl": {
        "type": "string",
        "title": "Dashboard Page URL",
        "description": ""
      },
      "managementDashboard": {
        "type": "string",
        "title": "Management Dashboard",
        "description": ""
      }
    }
  },
  "relations": {},
  "referenceProperties": {},
  "options": {
    "showInSideBar": true,
    "propertiesGroups": {}
  }
}
```

</details>

### Environment

The Environment blueprint encapsulates different deployment environments, such as production or testing.

<details>

<summary>Blueprint Descriptor</summary>

```json
{
  "id": "environment",
  "title": "Environment",
  "description": "",
  "icon": "house",
  "schemaProperties": {
    "type": "object",
    "properties": {
      "cost-dashboard": {
        "type": "string",
        "title": "Cost Dashboard",
        "format": "url",
        "description": ""
      },
      "observability-dashboard": {
        "type": "string",
        "title": "Observability Dashboard",
        "format": "url",
        "description": ""
      }
    }
  },
  "relations": {},
  "referenceProperties": {},
  "options": {
    "showInSideBar": true,
    "propertiesGroups": {}
  }
}
```

</details>

### Running Service

A Running Service represents an instance of a service actively running within an environment. This blueprint includes detailed monitoring and configuration properties. Relations are established with the base Service blueprint, the Resources supporting the service, and the Environment in which it is deployed, illustrating the dynamic aspects of service management.

<details>

<summary>Blueprint Descriptor</summary>

```json
{
  "id": "running-service",
  "title": "Running Service",
  "description": "",
  "icon": "curlyBrackets",
  "schemaProperties": {
    "type": "object",
    "properties": {
      "errors": {
        "type": "query",
        "title": "Errors",
        "format": "timeseries"
      },
      "base-url": {
        "type": "string",
        "title": "Base URL",
        "description": "The base URL where the service instance is accessible."
      },
      "requests": {
        "type": "query",
        "title": "Requests",
        "format": "timeseries"
      },
      "cpu-limit": {
        "type": "number",
        "title": "CPU Limit",
        "description": ""
      },
      "image-tag": {
        "type": "string",
        "title": "Image Tag",
        "description": "The deployed image tag"
      },
      "commit-sha": {
        "type": "string",
        "title": "Commit SHA",
        "description": ""
      },
      "helm-values": {
        "type": "string",
        "title": "Helm Values",
        "format": "yaml",
        "description": ""
      },
      "latency-p99": {
        "type": "query",
        "title": "Latency P99",
        "format": "timeseries"
      },
      "memory-limit": {
        "type": "string",
        "title": "Memory Limit",
        "description": ""
      },
      "logs-dashboard": {
        "type": "string",
        "title": "Logs Dashboard",
        "format": "url",
        "description": ""
      },
      "last-deployed-at": {
        "type": "string",
        "title": "Last Deployed At",
        "format": "date-time",
        "description": "The date and time when this service instance was last deployed."
      },
      "desired-number-replicas": {
        "type": "number",
        "title": "Desired Number of Replicas",
        "description": ""
      },
      "observability-dashboard": {
        "type": "string",
        "title": "Observability Dashboard",
        "format": "url",
        "description": ""
      }
    }
  },
  "relations": {
    "service": {
      "array": false,
      "title": "Service",
      "value": "service",
      "description": ""
    },
    "resources": {
      "array": true,
      "title": "Resources",
      "value": "resource",
      "description": "The Cloud Resources that support this service instance."
    },
    "environment": {
      "array": false,
      "title": "Environment",
      "value": "environment",
      "description": ""
    },
    "_.relatedPluginIds": {
      "array": true,
      "title": "(System) Related Plugins",
      "value": "_relyio.plugins_config.grafana_cloud",
      "description": "Related plugins for this entity"
    }
  },
  "referenceProperties": {},
  "options": {
    "showInSideBar": true,
    "propertiesGroups": {}
  }
}
```

</details>

### Deployment

This blueprint details the deployment processes for services, including timing, approval, and status. It is related to both Services, indicating what is being deployed, and Running Services, showing the outcome of deployments. This highlights its role in tracking and managing deployment activities within the software lifecycle.

<details>

<summary>Blueprint Descriptor</summary>

```json
{
  "id": "deployment",
  "title": "Deployment",
  "description": "",
  "icon": "arrowUp",
  "schemaProperties": {
    "type": "object",
    "properties": {
      "date": {
        "type": "string",
        "title": "Date",
        "format": "date-time",
        "description": ""
      },
      "duration": {
        "type": "string",
        "title": "Duration",
        "description": ""
      },
      "approved-by": {
        "type": "string",
        "title": "Approved By",
        "description": ""
      },
      "commit-hash": {
        "type": "string",
        "title": "Commit Hash",
        "description": ""
      },
      "pipeline-id": {
        "type": "string",
        "title": "Pipeline ID",
        "description": ""
      },
      "triggered-by": {
        "type": "string",
        "title": "Triggered By",
        "description": ""
      },
      "pipeline-link": {
        "type": "string",
        "title": "Pipeline Link",
        "description": ""
      },
      "deployment-status": {
        "type": "string",
        "title": "Deployment Status",
        "description": ""
      }
    }
  },
  "relations": {
    "service": {
      "array": true,
      "title": "Service",
      "value": "service",
      "description": ""
    },
    "running-service": {
      "array": true,
      "title": "Running Service",
      "value": "running-service",
      "description": ""
    }
  },
  "referenceProperties": {},
  "options": {
    "showInSideBar": true,
    "propertiesGroups": {}
  }
}
```

</details>

### Feature

The Feature blueprint is used to describe specific functionalities or features within services, including documentation, ownership, and related analytics dashboards. It is linked to Services that support the feature, pointing to its role in outlining how different services contribute to broader business functionalities.

<details>

<summary>Blueprint Descriptor</summary>

```json
{
  "id": "feature",
  "title": "Feature",
  "description": "",
  "icon": "book",
  "schemaProperties": {
    "type": "object",
    "properties": {
      "docs": {
        "type": "string",
        "title": "Docs",
        "format": "url",
        "description": "Feature Documentation Link"
      },
      "owner": {
        "type": "string",
        "title": "Owner",
        "description": "Names or role of the key stakeholders responsible by the feature."
      },
      "analytics-dashboard": {
        "type": "string",
        "title": "Analytics Dashboard",
        "description": "Data on user engagement or success metrics related to the journey."
      },
      "business-criticality": {
        "enum": [
          "P0",
          "P1",
          "P2"
        ],
        "type": "string",
        "title": "Business Criticality",
        "description": "The importance or impact level of this user journey on business operations."
      }
    }
  },
  "relations": {
    "services": {
      "array": true,
      "title": "Services",
      "value": "service",
      "description": "Services that directly support this feature."
    }
  },
  "referenceProperties": {},
  "options": {
    "showInSideBar": true,
    "propertiesGroups": {}
  }
}
```

</details>

### Domain

The Domain blueprint defines high-level business domains, such as functional areas or product lines. It includes properties concerning documentation, ownership, and business objectives. Relationships are formed with Features and Services, indicating the domain's encompassing role over specific functionalities and the services that implement them.

<details>

<summary>Blueprint Descriptor</summary>

```json
{
  "id": "domain",
  "title": "Domain",
  "description": "Defines a high-level business domain",
  "icon": "stack",
  "schemaProperties": {
    "type": "object",
    "properties": {
      "docs": {
        "type": "string",
        "title": "Docs",
        "format": "url",
        "description": "Domain Documentation Link"
      },
      "owner": {
        "type": "string",
        "title": "Owner",
        "description": "Names or role of the key stakeholders responsible by the feature."
      },
      "criticality": {
        "enum": [
          "P0",
          "P1",
          "P2"
        ],
        "type": "string",
        "title": "Criticality",
        "description": "The importance or impact level of this user journey on business operations."
      },
      "target-audience": {
        "enum": [
          "Customers",
          "Internal Stakeholders"
        ],
        "type": "string",
        "title": "Target Audience",
        "description": ""
      },
      "business-objectives": {
        "type": "string",
        "title": "Business Objectives",
        "description": "Key business objectives or goals associated with the domain."
      }
    }
  },
  "relations": {
    "features": {
      "array": true,
      "title": "Features",
      "value": "feature",
      "description": "The features that are part of or related to this business domain."
    },
    "services": {
      "array": true,
      "title": "Services",
      "value": "service",
      "description": "The services that support this business domain."
    }
  },
  "referenceProperties": {},
  "options": {
    "showInSideBar": true,
    "propertiesGroups": {}
  }
}
```

</details>

## Learn More

<table data-view="cards"><thead><tr><th>Blueprint Actions</th></tr></thead><tbody><tr><td><a href="/software-catalog/usage-guide/creating-a-new-blueprint-and-catalog">Creating a new Blueprint</a></td></tr><tr><td><a href="/software-catalog/usage-guide/updating-a-blueprint">Updating a Blueprint</a></td></tr><tr><td><a href="/software-catalog/usage-guide/tracking-blueprint-changes">Tracking Blueprint Changes</a></td></tr></tbody></table>


# Plugins

Plugins are the primary method for importing data into your catalogs. [Rely.io](http://Rely.io)'s flexible design allows integration with any tool, enabling you to build a software catalog tailored to your specific needs.

Rely supports both pull-based and push-based plugins through its [Public API](/public-api). It also offers plug-and-play integrations with many popular data sources. Choose an integration to discover how it can enhance your [Rely.io](http://Rely.io) platform.

<table data-view="cards"><thead><tr><th></th><th></th><th data-type="content-ref"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/argo-cd">Argo CD</a></td><td></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/aws">AWS</a></td><td></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/azure">Azure</a></td><td></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/backstage">Backstage</a></td><td></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/bitbucket">Bitbucket</a></td><td><a href="/plugins-and-automation/plugin-installation-guides/bitbucket">Bitbucket</a></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/datadog">Datadog</a></td><td></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/github">GitHub</a></td><td></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/gitlab">GitLab</a></td><td></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/google-cloud-platform-gcp">Google Cloud Platform (GCP)</a></td><td></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/grafana-cloud">Grafana Cloud</a></td><td></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/jira">Jira</a></td><td></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/kubernetes">Kubernetes</a></td><td></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/new-relic">New Relic</a></td><td></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/notion">Notion</a></td><td></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/opsgenie">OpsGenie</a></td><td></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/pagerduty">PagerDuty</a></td><td></td></tr><tr><td></td><td></td><td><a href="/plugins-and-automation/plugin-installation-guides/sonarqube">SonarQube</a></td><td></td></tr></tbody></table>


# User Blueprints vs Plugin Blueprints

Rely.io distinguishes between two types of blueprints: [User Blueprints](#user-blueprints) and [Plugin Blueprints](#plugin-blueprints).&#x20;

## Plugin Blueprints

Plugin Blueprints are predefined by Rely.io and define each native plugin's data model. These blueprints (and its entities) are not editable by users, ensuring stability and integrity of the plugin's functionality.

When installing (some) plugins, you may select assets of interest. The selected assets determine which Plugin Blueprints are incorporated into your own data model.&#x20;

{% hint style="info" %}
By default, plugin blueprints are located in the 'hidden' section of your data model builder and in the 'hidden' section of the Software Catalog sidebar.
{% endhint %}

These blueprints establish the structure for entities that Rely.io automatically retrieves and maintains through its entity discovery process. This automation keeps your catalogs consistently up-to-date without any manual intervention required.&#x20;

Entities created from plugin blueprints serve as an accurate reflection of data from your development tools, acting as the definitive source of truth for the information Rely.io ingests.

## User Blueprints

In contrast, User Blueprints are fully customizable. They are created and managed by users to tailor its Rely.io environment to specific organizational needs. These blueprints allow for flexibility and adaptability in defining and managing the entities within your software catalog.

{% hint style="info" %}
Entities derived from User Blueprints are editable through multiple methods:&#x20;

* Directly via the Rely UI
* Programmatically via the public API
* Or through [automation rules](/basic-concepts/actions-and-automations/automation-rules), which allow you to map and manipulate data from plugin blueprint entities onto user blueprint entities.
  {% endhint %}

To learn more about the user blueprints that rely enables out-of-the-box, checkout the [default data model](/basic-concepts/data-model#default-data-model).


# Actions and Automations

Rely.io focuses on automating and simplifying developer workflows through the use of two powerful tools:

* Automations
* Self-Service Actions

## Automations

Data can be mapped from [Plugin Blueprint](/basic-concepts/user-blueprints-vs-plugin-blueprints#plugin-blueprints) entities to [User Blueprint](/basic-concepts/user-blueprints-vs-plugin-blueprints#user-blueprints) entities via automation rules.&#x20;

This mapping creates a dynamic abstraction layer, allowing data from various sources to be filtered, manipulated, standardized, and centralized according to your needs. Automation Rules serve two main purposes:

1. Unified Entity Representation: Different tools like git providers, incident management tools, and observability platforms represent a "Service" in various ways. Automation rules and user blueprints let you aggregate these diverse perspectives into a single, cohesive "Service" entity. This entity contains only what matters most from each source and reflects your organization's operational context.
2. Standardizing Cross-Tool Entities: For example, pull requests and merge requests from both GitHub and GitLab can be standardized into a unified format, as can issues from both Jira and Linear. This standardization enables large organizations to maintain uniformity and clarity in their Internal Developer Platform (IDP) across different team processes and toolsets.

{% hint style="info" %}
Rely.io takes a proactive approach by offering **pre-configured automation rules** for common use cases, which are automatically included when you install certain plugins.&#x20;

These default automation rules leverage:

* [The specific data model associated with each plugin](/basic-concepts/user-blueprints-vs-plugin-blueprints#plugin-blueprints)
* [The out-of-the-box data model Rely offers when first creating your organization](/basic-concepts/data-model#default-data-model)

These rules are designed to streamline processes and ensure seamless integration of plugin data with the most common [user blueprints](/basic-concepts/user-blueprints-vs-plugin-blueprints#user-blueprints).&#x20;
{% endhint %}

## Self-Service Actions


# Automation Rules

## Automation Rule Descriptor

Regardless of whether you're using UI editing or GitOps to manage your automation rules, the definitions are backed by JSON files. Each file is a fully compliant OpenAPI 3 spec file, with our own specific extensions.

{% hint style="info" %}
**You can still use Automation Rules even if you don't use OpenAPI/Swagger.**

We use the OpenAPI spec as a base for automation rule configuration, since it's an open spec with official support for extensions. That lets us extend it to be an automation rule descriptor spec with optional usage of actual OpenAPI fields.
{% endhint %}

All automation rule descriptors have 5 metadata fields:

* **ID**: A unique identifier for the rule.
* **Name**: A user-friendly display name.
* **Description** (Optional): A concise overview of the rule for further context.
* **Is Active**: Boolean parameter that determines whether the rule is active and should be executed or not.
* **Type:** Define the type of rule (`automation`) .

### Arguments

* **Source Blueprint ID**: The identifier for the blueprint, whose entities creation or update trigger the rule.
* **Target Blueprint ID**: The identifier for the blueprint, whose entities will be affected by the rule.

Example

```json
  "arguments": {
    "sourceBlueprintId": "gitlab.v1.repository",
    "targetBlueprintId": "service"
  }
```

### Triggers

Triggers are conditions that initiate the execution of an automation rule. For a trigger to activate, specific events must occur within the system that match the defined criteria in the trigger settings.&#x20;

Here’s how you can set up a trigger:

* **Type:** Only available type for automations is `onEvent`.&#x20;
* **Event**: Specify the exact event or action needed to trigger the automation. Currently, this is limited to the creation, modification, or both, of an entity.
* **Conditions**: Define the criteria that must be met for the trigger to activate based on the event's details. This typically involves checking a field's value within an entity against a predefined value or expression to ensure only the desired entities trigger the automation.

Example:

```json
"triggers": [
    {
      "type": "onEvent",
      "conditions": [
        {
          "field": "data.blueprintId",
          "operator": "eq",
          "value": "{{ arguments.sourceBlueprintId }}"
        }
      ],
      "event": {
        "resource": "entity",
        "action": [
          "create",
          "update"
        ]
      }
    }
  ]
```

### Actions&#x20;

Actions are the operations executed by the automation rule when a trigger condition is met. Actions are executed sequentially in the order they appear within the list of `actions`. This ensures that each action can depend on the outcomes of previous actions, allowing for complex workflows. Currently there are two type of actions available:

* **UpsertResource**: This action ensures that the target entity is updated with the latest data from the source entity by creating a new resource if it does not exist or updating it if it does.
* **FetchResource**: This action retrieves data from an existing entity. It can be utilized to gather additional information required for completing an upsert operation or for implementing conditional logic within complex automations.
* **HttpRequest:** This action sends an HTTP request to an external service or API. It allows for communication with third-party services, enabling the automation to interact with external systems, retrieve data, or send updates. The HttpRequest action can be configured to perform GET, POST, PUT, or DELETE operations, depending on the needs of the automation workflow.

{% hint style="info" %}
The`stopFlowIfNotFound`flag available for `fetchResource` actions can halt further execution of a workflow, thus preventing unnecessary actions or errors in cases where essential data is missing.&#x20;
{% endhint %}

Example:

```json
"actions": [
    {
      "type": "upsertResource",
      "args": {
        "data": {
          "id": "{{ data.id }}.service",
          "title": "Service {{ data.title }}",
          "relations": {
            "GitlabRepository": {
              "value": "{{ data.id }}"
            }
          },
          "properties": {
            "readme": "{{ data.properties.readme }}",
            "repo-link": "{{ data.properties.url }}"
          },
          "blueprintId": "{{ arguments.targetBlueprintId }}",
          "description": "The resource {{ data.title }}"
        },
        "resourceType": "entity"
      }
    }
  ]
```

### Data Manipulation

Automation Rules in Rely leverage the power of the [JINJA2 templating engine](https://jinja.palletsprojects.com/en/3.1.x/templates/), which allows for data manipulation using a syntax resembling Python. To use Jinja in your templates, you need to enclose expressions in double curly braces: `{{  ...  }}`.

Automation Rules can access data from:

* **The entity that triggered the automation:** This data is accessible through the `data` variable, which points to the root of the entity descriptor. This enables the template to dynamically incorporate attributes of the triggering entity into the automation actions. For example, you can reference an entity’s name with `{{  data.id  }}`.
* **The outputs of previous fetchResource actions within the same rule:** These outputs can be accessed via `actions.ACTION-ID-HERE.output`. This allows subsequent actions to utilize and build upon the results of earlier actions, enabling complex, dependent workflows that adapt based on prior outputs. For instance, if a previous action has an ID of `fetch_user`, you can access its output with `{{  actions.fetch_user.output  }}`.
* **The automation rule descriptor itself:** Fields at the root of the descriptor can be directly referenced. For example, to reference the source blueprint ID, you would use `{{  arguments.sourceBlueprintId  }}`.

To further explore and experiment with Jinja templating, you can use online resources such as  [Jinja Live Parser](http://jinja.quantprogramming.com/). This tool provides a hands-on way to practice and visualize how Jinja processes data, aiding in the development and testing of your automation rules.

## Suggestions

{% hint style="info" %}
Automation rules can generate suggestions instead of directly creating entities in your software catalog.  Suggestions are fully formed entities that are ready to be added to your catalog but require manual approval to be accepted.
{% endhint %}

Suggestions are designed to give you control over what data is added to your catalog, ensuring it remains relevant and valuable to your organization. This prevents unnecessary clutter or irrelevant data from being included.

To enable the creation of suggestions instead of entities, you can set the `createSuggestion` flag to true within the `UpsertResource` action of your automation rule configuration. Once generated, suggestions can be managed through the [Discovery](https://webapp.rely.io/data-model/discovery) tab in Rely.io. Here, you can review, approve, and accept suggestions to be officially added to your catalog.

{% hint style="info" %}
Most of Rely's default automation rules are configured to generate suggestions by default. This approach ensures that you have the opportunity to review and validate each entity before it becomes a permanent part of your catalog.
{% endhint %}

## Examples

### Example 1 (Gitlab Repo -> Service)

When a new repository being found or a known one is updated, the automation either creates a new service entity or updates an existing one using the repository ID, README, and the repository link.

```json
{
  "id": "rely.gitlab.v1.repository-to-service",
  "title": "GitLab Repository to Service",
  "description": "This automation creates a service from a GitLab repository",
  "isActive": true,
  "type": "automation",
  "arguments": {
    "sourceBlueprintId": "gitlab.v1.repository",
    "targetBlueprintId": "service"
  },
  "triggers": [
    {
      "type": "onEvent",
      "conditions": [
        {
          "field": "data.blueprintId",
          "operator": "eq",
          "value": "{{ arguments.sourceBlueprintId }}"
        }
      ],
      "event": {
        "resource": "entity",
        "action": [
          "create",
          "update"
        ]
      }
    }
  ],
  "actions": [
    {
      "type": "upsertResource",
      "args": {
        "data": {
          "id": "{{ data.id }}.service",
          "title": "Service {{ data.title }}",
          "relations": {
            "GitlabRepository": {
              "value": "{{ data.id }}"
            }
          },
          "properties": {
            "readme": "{{ data.properties.readme }}",
            "repo-link": "{{ data.properties.url }}"
          },
          "blueprintId": "{{ arguments.targetBlueprintId }}",
          "description": "The resource {{ data.title }}"
        },
        "resourceType": "entity"
      }
    }
  ]
}
```

### Example 2 (ArgoCD Application -> Running Service)

When an ArgoCD application is created or updated, the rule fetches corresponding service and environment entities based on predefined labels (`x-rely-service` & `x-rely-environment`) and creates or updates a "Running Service" entity.

This entity is then linked to the environment where it's running in, the specific service it's associated with and the original ArgoCD application.

```json
{
  "id": "rely.argocd.v1.application-to-running-service",
  "title": "ArgoCD Application to Running-Service",
  "description": "",
  "isActive": true,
  "type": "automation",
  "arguments": {
    "sourceBlueprintId": "argocd.v1.application",
    "targetBlueprintId": "running-service"
  },
  "secrets": {},
  "triggers": [
    {
      "type": "onEvent",
      "event": {
        "resource": "entity",
        "action": [
          "create",
          "update"
        ]
      }
    }
  ],
  "actions": [
    {
      "type": "fetchResource",
      "args": {
        "default": {
          "id": "{{ data.properties.labels['x-rely-service'].replace('-', '.') }}.service",
          "properties": {
            "externalUrls": []
          }
        },
        "conditions": [
          {
            "field": "id",
            "value": "{{ data.properties.labels['x-rely-service'].replace('-', '.') }}.service",
            "operator": "eq"
          },
          {
            "field": "blueprintId",
            "value": "service",
            "operator": "eq"
          }
        ],
        "resourceType": "entity",
        "stopFlowIfNotFound": true
      },
      "id": "matching_service"
    },
    {
      "type": "fetchResource",
      "args": {
        "default": {
          "id": "environment.{{ data.properties.labels['x-rely-environment'] }}"
        },
        "conditions": [
          {
            "field": "id",
            "value": "environment.{{ data.properties.labels['x-rely-environment'] }}",
            "operator": "eq"
          },
          {
            "field": "blueprintId",
            "value": "environment",
            "operator": "eq"
          }
        ],
        "resourceType": "entity",
        "stopFlowIfNotFound": true
      },
      "id": "matching_environment"
    },
    {
      "type": "upsertResource",
      "args": {
        "data": {
          "id": "{{ data.id }}.running-service",
          "title": "{{ data.properties.labels['x-rely-service'] }}-{{ data.properties.labels['x-rely-environment'] }}",
          "relations": {
            "service": {
              "value": "{{ actions.matching_service.output.id }}"
            },
            "environment": {
              "value": "{{ actions.matching_environment.output.id }}"
            },
            "argo-application": {
              "value": "{{ data.id }}"
            }
          },
          "properties": {
            "tags": "{{ data.properties.labels }}",
            "base-url": "{{ (data.properties.externalUrls[0] if data.properties and data.properties.externalUrls and data.properties.externalUrls|length > 0 else '') }}",
            "image-tags": "{{ data.properties.images }}",
            "sync-status": "{{ data.properties.status.health }}",
            "last-deployed-at": "{{ data.properties.status.lastSync.finishedAt }}",
            "automatic-deploys-enabled": "{{ data.properties.syncPolicy.automated.prune if data.properties and data.properties.syncPolicy and data.properties.syncPolicy.automated and data.properties.syncPolicy.automated.prune else 'Unknown' }}"
          },
          "blueprintId": "{{ arguments.targetBlueprintId }}",
          "description": ""
        },
        "resourceType": "entity"
      },
      "id": "create_running_service"
    }
  ]
}
```

### Example 3 (Gitlab Pipeline -> Deployment)

This automation rule maps a Gitlab pipeline to a "Deployment" entity, specifically targeting production deployments.&#x20;

It activates when a pipeline, associated with designated repositories and marked for release, is created or updated.&#x20;

The rule fetches the service related to the pipeline and updates or creates a deployment entity capturing details such as the deployment status, start and finish times, and the individual who triggered the pipeline, enhancing traceability and oversight of deployment activities.

```json
{
  "id": "rely.gitlab.v1.pipeline-to-deployment",
  "title": "GitLab Pipeline to Deployment (Prod): magneto,integrations,flow.engine,applications.config,",
  "description": "",
  "isActive": true,
  "type": "automation",
  "arguments": {
    "sourceBlueprintId": "gitlab.v1.pipeline",
    "targetBlueprintId": "deployment"
  },
  "secrets": {},
  "triggers": [
    {
      "type": "onEvent",
      "conditions": [
        {
          "field": "data.blueprintId",
          "operator": "eq",
          "value": "{{ arguments.sourceBlueprintId }}"
        },
        {
          "field": "data.properties.branch",
          "operator": "like",
          "value": "release%"
        },
        {
          "field": "data.relations.repository.value",
          "operator": "in",
          "value": "magneto,integrations,flow.engine,applications.configuration"
        }
      ],
      "event": {
        "resource": "entity",
        "action": [
          "create",
          "update"
        ]
      }
    }
  ],
  "actions": [
    {
      "type": "fetchResource",
      "args": {
        "conditions": [
          {
            "field": "blueprintId",
            "value": "service",
            "operator": "eq"
          },
          {
            "field": "relations/GitlabRepository/value",
            "value": "{{ data.relations.repository.value }}",
            "operator": "eq"
          }
        ],
        "resourceType": "entity",
        "stopFlowIfNotFound": true
      },
      "id": "fetch_service"
    },
    {
      "type": "upsertResource",
      "args": {
        "data": {
          "id": "{{ data.id }}.deployment",
          "title": "Deployment {{ data.properties.branch }}",
          "relations": {
            "service": {
              "value": "{{ actions.fetch_service.output.id }}"
            },
            "environment": {
              "value": "environment.prod"
            }
          },
          "properties": {
            "startedAt": "{{ data.properties.startedAt }}",
            "finishedAt": "{{ data.properties.finishedAt }}",
            "pipelineId": "{{ data.id | string }}",
            "triggeredBy": "{{ data.properties.triggeredBy }}",
            "pipelineLink": "{{ data.properties.webUrl }}",
            "statusGitlab": "{{ data.properties.status }}",
            "durationGitlab": "{{ data.properties.duration }}"
          },
          "blueprintId": "{{ arguments.targetBlueprintId }}"
        },
        "resourceType": "entity"
      },
      "id": "update_deployment"
    },
    {
      "type": "fetchResource",
      "args": {
        "conditions": [
          {
            "field": "blueprintId",
            "value": "user",
            "operator": "eq"
          },
          {
            "field": "properties/aliases",
            "value": "{{ data.properties.triggeredBy }}",
            "operator": "contains"
          }
        ],
        "resourceType": "entity",
        "stopFlowIfNotFound": true
      },
      "id": "fetch_user"
    },
    {
      "type": "upsertResource",
      "args": {
        "data": {
          "id": "{{ data.id }}.deployment",
          "title": "Deployment {{ data.properties.branch }}",
          "relations": {
            "triggeredByUser": {
              "value": "{{ actions.fetch_user.output.id }}"
            }
          },
          "properties": {},
          "blueprintId": "{{ arguments.targetBlueprintId }}"
        },
        "resourceType": "entity"
      },
      "id": "update_deployment_2"
    },
    {
      "type": "fetchResource",
      "args": {
        "conditions": [
          {
            "field": "blueprintId",
            "value": "running-service",
            "operator": "eq"
          },
          {
            "field": "relations/environment/value",
            "value": "environment.prod",
            "operator": "in"
          },
          {
            "field": "relations/service/value",
            "value": "{{ actions.fetch_service.output.id }}",
            "operator": "in"
          }
        ],
        "resourceType": "entity",
        "stopFlowIfNotFound": true
      },
      "id": "fetch_running_service"
    },
    {
      "type": "upsertResource",
      "args": {
        "data": {
          "id": "{{ data.id }}.deployment",
          "title": "Deployment {{ data.properties.branch }}",
          "relations": {
            "runningService": {
              "value": "{{ actions.fetch_running_service.output.id }}"
            }
          },
          "properties": {},
          "blueprintId": "{{ arguments.targetBlueprintId }}"
        },
        "resourceType": "entity"
      },
      "id": "update_deployment_3"
    }
  ]
}
```

## Learn More

<table data-view="cards"><thead><tr><th>Automation Actions</th></tr></thead><tbody><tr><td><a href="/plugins-and-automation/automation-rules/usage-guide/creating-an-automation-rule">Creating an Automation Rule</a></td></tr><tr><td><a href="/plugins-and-automation/automation-rules/usage-guide/updating-an-automation-rule">Updating an Automation Rule</a></td></tr><tr><td><a href="/plugins-and-automation/automation-rules/usage-guide/tracking-automation-changes">Tracking Automation Changes</a></td></tr><tr><td><a href="/plugins-and-automation/automation-rules/usage-guide/managing-automation-suggestion">Managing Automation Suggestions</a></td></tr></tbody></table>


# Self-Service Actions

## Self-Service Action Descriptor

Regardless of whether you're using UI editing or GitOps to manage your self-service actions, the definitions are backed by JSON files. Each file is a fully compliant OpenAPI 3 spec file, with our own specific extensions.

{% hint style="info" %}
**You can still use Self Service Actions even if you don't use OpenAPI/Swagger.**

We use the OpenAPI spec as a base for automation rule configuration, since it's an open spec with official support for extensions. That lets us extend it to be an automation rule descriptor spec with optional usage of actual OpenAPI fields.
{% endhint %}

All automation rule descriptors have 5 metadata fields:

* **ID**: A unique identifier for the rule.
* **Name**: A user-friendly display name.
* **Description** (Optional): A concise overview of the action for further context.
* **Is Active**: Boolean parameter that determines whether the self-service-action is active and should be executed or not.
* **Type:** Defines the type of rule (`selfServiceAction`) .

### Triggers

Triggers are conditions that initiate the execution. For self-service actions, the only available trigger type is `manual` meaning users need to manual execute the action either via the UI or API.

The trigger sections also specify the arguments (and their data-types) that a self-service action requires to be triggered, which are used as input when triggering an action from the UI.

E.g.

```json
"triggers": [
   {
      "type":"manual",
      "inputSchema":{
         "type":"object",
         "title":"Repository Details",
         "required":[
            "repositoryName",
            "visibility"
         ],
         "properties":{
            "repositoryName":{
               "type":"string",
               "title":"Repository Name",
               "description": "The name of the Repository in Gitlab"
            },
            "visibility":{
               "type":"string",
               "title":"Visibility",
               "description": "The visibility of the Repository ('hidden', 'internal', 'public')",
               "enum": ["private", "internal", "public"],
               "default":"hidden"
            }
         }
      }
   }
]
```

### Actions

Actions are the operations executed by the automation rule when a trigger condition is met. Actions in self-service action rules resemble the schema and syntax of [actions in automation rules](/basic-concepts/actions-and-automations/automation-rules#actions).

### Data Manipulation

Data Manipulation in self-service action rules resemble the behaviour of actions in [automation rules](/basic-concepts/actions-and-automations/automation-rules#data-manipulation).

### Example 1 (Creating a Gitlab Repository)

```json
{
	"id": "gitlab-repo-creation",
	"title": "Create Repository in GitLab",
	"description": "Create a new GitLab repository",
	"isActive": true,
	"order": 0,
	"type": "selfServiceAction",
	"arguments": {},
	"triggers": [
   {
      "type":"manual",
      "inputSchema":{
         "type":"object",
         "title":"Repository Details",
         "required":[
            "repositoryName",
            "visibility"
         ],
         "properties":{
            "repositoryName":{
               "type":"string",
               "title":"Repository Name",
               "description": "The name of the Repository in Gitlab"
            },
            "visibility":{
               "type":"string",
               "title":"Visibility",
               "description": "The visibility of the Repository ('hidden', 'internal', 'public')",
               "enum": ["private", "internal", "public"],
               "default":"hidden"
            }
         }
      }
	}],
	"actions": [{
	   "type": "httpRequest",
	   "args": {
		   "body": "{\"name\": \"{{ data.repositoryName }}\", \"visibility\": \"{{ data.visibility }}\"}",
		   "path": "",
		   "method": "post",
		   "baseUrl": "https://gitlab.com/api/v4/projects",
		   "headers": {
			   "Content-Type": "application/json",
			   "PRIVATE-TOKEN": "{{ env('GITLAB_TOKEN_ID') }}"
		   }
	   }
        }],
	"tags": [{
      "key": "data-source",
      "value": "gitlab"
    }]
}
```

## Learn More

<table data-view="cards"><thead><tr><th>Self Service Actions</th></tr></thead><tbody><tr><td><a data-mention href="/self-service-actions/usage-guide/configuring-your-self-service-agent">Configuring your Self Service Agent</a></td></tr><tr><td><a data-mention href="/self-service-actions/usage-guide/running-actions">Running Actions</a></td></tr><tr><td><a data-mention href="/self-service-actions/usage-guide/tracking-action-runs">Tracking Action Runs</a></td></tr></tbody></table>


# Home Pages

The Home Page is designed to streamline and centralize the daily activities of developers, reducing the need for context switching and the inefficiency of navigating multiple tools. It offers quick access to the most actionable [catalogs](/basic-concepts/catalogs) in Rely.&#x20;

While each user can configure their own tabs, the Home Page include the following tabs out-of-the-box:

* **My Services:** Sub-set of the service catalog focused on the services related to the current user.
* **My Issues:** Lists issues assigned to the user (populated by project management plugins).
* **Open Pull Requests:** Lists open pull/merge requests opened by the current user that are under review (populated by git provider plugins).
* **Assigned Pull Requests:** Lists open pull/merge requests to which the current user is assigned for review in (populated by git provider plugins).

{% hint style="info" %}
Unlike standard catalog pages, any customisations applied to catalogs on your Home Page are unique to your user profile. For these customisations, you can utilize all standard data manipulation features common across [Rely catalogs](/basic-concepts/catalogs), such as filtering, grouping, and sorting.
{% endhint %}

## Learn More

<table data-view="cards"><thead><tr><th>HomePage Actions</th></tr></thead><tbody><tr><td><a href="/home-pages/usage-guide/creating-a-new-tab">Creating a Home Page Tab</a></td></tr></tbody></table>


# Scorecards

## Scorecard Descriptor

Regardless of whether you're using UI editing or GitOps to manage your scorecards, the definitions are backed by JSON files. Each file is a fully compliant OpenAPI 3 spec file, with our own specific extensions.

{% hint style="info" %}
**You can still use Scorecards even if you don't use OpenAPI/Swagger.**

We use the OpenAPI spec as a base for scorecard configuration, since it's an open spec with official support for extensions. That lets us extend it to be a scorecard descriptor spec with optional usage of actual OpenAPI fields.
{% endhint %}

All scorecard descriptors have 5 metadata fields:

* **ID**: A unique identifier for the scorecard.
* **Title**: A user-friendly display name.
* **Description** (Optional): A concise overview of the scorecard for further context.
* **Blueprint ID**: References the type of entity the scorecard applies to.
* **Is Active**: Indicates whether the scorecard is active and currently being applied to or not.

### Ranks

The "Ranks" section of a Scorecard in Rely defines the performance tiers or levels that an entity can achieve based on predefined criteria.  The available ranks are "bronze," "silver," or "gold". Each rank is associated with a set of rules that determine the conditions under which an entity qualifies for that specific rank.&#x20;

{% hint style="info" %}
Ranks in the scorecard descriptor should be sorted in ascending order, starting with the lowest rank: bronze, followed by silver, then gold.
{% endhint %}

Ranks help categorize performance or compliance levels in a structured way, allowing organisations to easily identify and prioritise areas for improvement or recognition.

### Rules

Rules utilize the properties outlined in the blueprint to which the scorecard is applied, allowing for the comparison of each entity's defined value against a threshold value.

Each rule is defined by:

* **ID**: A unique identifier for the rule.
* **Title**: A user-friendly display name.
* **Description (optional)**: A concise overview of the rule for further context.
* **Conditions**: A list of criteria that dictate how the data properties of the entity are evaluated. These conditions include:
  1. A property within the blueprint
  2. An operator (e.g., equal to, less than)
  3. And the value to compare against.

### Condition Operators

| Operator      | Name                  | Description                                                                         |
| ------------- | --------------------- | ----------------------------------------------------------------------------------- |
| `eq`          | Equals                | Tests whether the field's value is equal to the specified value.                    |
| `lt`          | Less Than             | Checks if the field's value is less than the specified value.                       |
| `lte`         | Less Than or Equal    | Determines if the field's value is less than or equal to the specified value.       |
| `gt`          | Greater Than          | Evaluates if the field's value is greater than the specified value.                 |
| `gte`         | Greater Than or Equal | Assesses if the field's value is greater than or equal to the specified value.      |
| `ne`          | Not Equal             | Verifies that the field's value is not equal to the specified value.                |
| `contains`    | Contains              | Checks if the field's value includes the specified substring or list element.       |
| `notcontains` | Not Contains          | Ensures the field's value does not include the specified substring or list element. |

## Example

```json
{
  "id": "service-dora-performance",
  "title": "DORA Performance",
  "description": "Measures DevOps team performance using DORA metrics, focusing on Deployment Frequency, Lead Time for Changes, Mean Time to Recovery, and Change Failure Rate.",
  "isActive": true,
  "blueprintId": "service",
  "ranks": [
    {
      "id": "bronze",
      "rules": [
        {
          "id": "no-rollbacks-last-30-days",
          "title": "No rollbacks in the last 30 days",
          "description": "Number of rollbacks in the last 30 days equals 0",
          "conditions": [
            {
              "field": "data.properties.rollbackcountlast30days",
              "operator": "eq",
              "value": 0
            }
          ]
        },
        {
          "id": "incident-deploy-ratio-zero",
          "title": "Ratio of incidents to deploys is zero",
          "description": "Ratio of incidents to deployments in the last 30 days equals 0",
          "conditions": [
            {
              "field": "data.properties.incidentdeployratiolast30days",
              "operator": "eq",
              "value": 0
            }
          ]
        },
        {
          "id": "rollback-deploy-ratio-zero",
          "title": "Ratio of rollbacks to deploys is zero",
          "description": "Ratio of rollbacks to deployments in the last 30 days equals 0",
          "conditions": [
            {
              "field": "data.properties.rollbackdeployratiolast30days",
              "operator": "eq",
              "value": 0
            }
          ]
        }
      ]
    },
    {
      "id": "silver",
      "rules": [
        {
          "id": "less-than-five-bugs-last-30-days",
          "title": "Less than 5 bugs in the last 30 days",
          "description": "Number of bugs in the last 30 days is less than 5",
          "conditions": [
            {
              "field": "data.properties.bugcountlast30days",
              "operator": "lt",
              "value": 5
            }
          ]
        },
        {
          "id": "less-than-five-incidents-last-30-days",
          "title": "Less than 5 incidents in the last 30 days",
          "description": "Number of incidents in the last 30 days is less than 5",
          "conditions": [
            {
              "field": "data.properties.incidentcountlast30days",
              "operator": "lt",
              "value": 5
            }
          ]
        }
      ]
    },
    {
      "id": "gold",
      "rules": [
        {
          "id": "incidents-acked-within-5-mins",
          "title": "Incidents acknowledged within 5 minutes",
          "description": "Mean time to acknowledge (MTTA) incidents is less than or equal to 300 seconds over the last 30 days",
          "conditions": [
            {
              "field": "data.properties.meantimetoacknowledge",
              "operator": "lte",
              "value": 300
            }
          ]
        },
        {
          "id": "incidents-resolved-in-1h",
          "title": "Incidents resolved in less than 1 hour",
          "description": "Number of incidents resolved in more than 1 hour is 0 over the last 30 days",
          "conditions": [
            {
              "field": "data.properties.incidentsresolvedover1h",
              "operator": "lte",
              "value": 0
            }
          ]
        },
        {
          "id": "no-incidents-last-30-days",
          "title": "No incidents in the last 30 days",
          "description": "Total number of incidents in the last 30 days equals 0",
          "conditions": [
            {
              "field": "data.properties.incidentcountlast30days",
              "operator": "eq",
              "value": 0
            }
          ]
        }
      ]
    }
  ],
  "medianRank": "silver"
}
```

## Learn More

<table data-view="cards"><thead><tr><th>Scorecard Actions</th></tr></thead><tbody><tr><td><a href="/scorecards/usage-guide/creating-a-scorecard">Creating a Scorecard</a></td></tr><tr><td><a href="/scorecards/usage-guide/updating-a-scorecard">Updating a Scorecard</a></td></tr><tr><td><a href="/scorecards/usage-guide/evaluating-performance">Evaluating Performance</a></td></tr></tbody></table>


# Guides & Tutorials


# Populating your Service Catalog with Github and Datadog

## **Github**

Installation is done by using the Rely.io integration page where you'll be redirected to GitHub App's integration form. Login to your GitHub account and submit the form by providing the necessary permissions (official docs[ here](https://docs.rely.io/data-sources/integrations/github)).&#x20;

Once you’re done, rely will be able to ingest the repositories, issues, pull-request, and workflows that it has access to. Upon installation Rely offers OOTB automation rules to best map the assets that are discovered in Github into entities in your software catalog. This will allow you to populate and meaningfully link entities in your software catalog automatically.&#x20;

From this point forward you can either go with the out-of-the-box rules or if you are feeling adventurous you can tweak the settings to your liking. The output of these automation rules will look something like this in your service catalog:

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FU7xySZSacRQieeUwiYac%2Fimage.png?alt=media&amp;token=a6d0afcd-bbbe-4be8-8125-aa476836f675" alt=""><figcaption><p>Service Catalog post Github installation</p></figcaption></figure>

### The default automation-rules for the Github plugin allow you to:

#### Import Github users into Rely that you later invite on-to the platform.

Having Users reflected as their own entity allows you to more easily keep track of ownership and activity even if they’re not an actual user in Rely just yet.

#### Import Github teams into Rely and automatically link them to their members & leaders according to the definitions in Github.

Import Repositories as Services and automatically link them to the teams, users, issues, pull-requests & workflows that have contributed to it, as well as to import relevant information like:

* The content of the README.
* The list of programming languages used in the repository.
* The number of open pull-requests & issues.

Such a Service will look more or less like this:

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FoPuvwcz2CxESfEqxVFAD%2Fimage.png?alt=media&amp;token=c3fbd890-4c01-4b82-bc08-a9e1a080da72" alt=""><figcaption><p>Service Details Page post Github Installation</p></figcaption></figure>

#### Import Workflow Runs that specifically target the repositories main branch as “deployment” entities to the “production” environment.&#x20;

Worry not, if this isn’t a suitable way for you to identify deployments in your organization, you can easily adjust the automation rule to target workflows with a specific label, a specific name nomenclature, etc. This will automatically link the deployment to the service, the user who triggered it, the one who approved it, the team they belong to and bringing information like:

* When was the deployment triggered
* How long did it take
* The commit hash
* The final status of the workflow
* The commit hash
* A link to the respective workflow
* Etc.

## **Datadog**

To get Datadog installed into Rely.io you’ll need to create an Application key in Datadog with the necessary scopes and permission (official docs[ here](https://docs.rely.io/data-sources/integrations/datadog)) and paste them into the two-step wizard in Rely.io. Now Rely will be able to ingest the services, hosts, cloud assets, metrics, and SLOs that your Datadog has access to.

### The default automation rules for the Datadog plugin work as follows:

When you import your Datadog users and teams  into Rely.io you can either merge them into the teams that have previously been created by the Github plugin or you can create entirely new entities from the ones&#x20;

Similarly to teams and users they can either create new entities or be merged into previously existing ones, thus fleshing them out even further with the relevant information found in Datadog:

* Metrics
* SLOs
* Links to Documentation
* Links to observability dashboards
* The different environments the service is deployed to
* Etc.

By default, if you you have the appropriated labels in place cloud assets can automatically be merged to the and environments they’re supporting and are populated with relevant information found in Datadog:

* Cloud Provider
* Asset Type
* IaC tooling
* IaC code definition
* Links to observability dashboards


# Enhancing Deployment Visibility through Gitlab Pipelines and Rely's API

## Step 1 - Generate a Rely API key

Begin by logging into your Rely account and navigating to the **`Data-Model > Plugins`** section. Here, you will find a listing for the Rely Public API.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FdjcrIhzORqPbIMfUOhee%2Fimage.png?alt=media&amp;token=2d8ec108-9faa-4489-84bc-adf8a60aae4b" alt="" width="188"><figcaption></figcaption></figure>

Click on “View details” to proceed:

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FmQtYOd6tH2k2Sfom53m8%2Fimage.png?alt=media&amp;token=9bde882e-e0cd-4b72-b8d4-c7988af01419" alt=""><figcaption></figcaption></figure>

To obtain your access token, simply click “Generate an API key”. This action copies the API key to your clipboard, ready for use - make sure to store it somewhere safe as it won’t be presented anywhere else.

These keys serve as credentials for authenticating access to Rely's Public API. To authenticate, include the key in the `Authorization` header of the API request, formatted as `"Bearer {your_token_here}"`. All available endpoints can be found in our [official documentation](https://docs.rely.io/public-api/overview).

#### **Token Expiration and Limitations**

Tokens created via this process are valid for a duration of 10 years.

💡 Currently, users are limited to one active token at any given time. **Generating a new token will automatically deactivate any previously issued token.**

## Step 2 - Set it as Variable in your CI/CD Pipeline

Log into your GitLab account to define CI/CD variables directly through the UI, which can be set at different levels for varying scopes of application:

* **Project Level:** Set variables specifically for a single project [in the project’s settings](https://docs.gitlab.com/ee/ci/variables/#for-a-project).
* **Group Level:** Apply variables to all projects within a group [in the group’s settings](https://docs.gitlab.com/ee/ci/variables/#for-a-group).
* **Instance Level:** Configure variables for all projects in your GitLab instance [in the instance’s settings](https://docs.gitlab.com/ee/ci/variables/#for-an-instance).

Choose the appropriate level for your needs and refer to GitLab’s official documentation for detailed guidance. At the relevant section, you can add a new CI/CD variable by clicking “Add variable”.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FHSsogHdMUtomf3VY0HQs%2Fimage.png?alt=media&amp;token=90973040-b508-4802-91c3-bc061e33b3fe" alt=""><figcaption></figcaption></figure>

* **Description**: Provide a clear description of the variable's purpose (e.g., "API token for interacting with [Rely.io](http://Rely.io)").
* **Key**: Assign a meaningful name for the variable (e.g., `RELY_API_TOKEN`).
* **Value**: Paste the private token you previously generated.

Ensure the correct configuration of your CI/CD variables to seamlessly integrate and automate your workflows with [Rely.io](http://Rely.io) through GitLab.

## Step 3 - Add Jobs to your CI/CD Pipeline

When setting up your CI/CD pipeline, you have the flexibility to integrate Rely in a way that best suits your workflow.

#### **Pipeline Job**

* **Specific Rely Update Jobs:** Create specific jobs within your pipeline to push updates to Rely. This can be a standalone job dedicated to this task.
* **Embedded Rely Update in an existing job:** Alternatively, incorporate the logic to communicate with Rely within existing jobs, depending on your pipeline structure.

#### **Frequency of Updates**

* **Single Update:** You might prefer to update Rely once, typically at the end of your pipeline, to reflect the outcome or final state. This means that if the pipeline fails, no entity will be created
* **Continuous Updates:** For more dynamic insights, consider updating Rely multiple times throughout your pipeline execution. This approach allows you to continuously reflect the pipeline's progress or changes in Rely. E.g.
  * **Initial Deployment Entity:** At the start of your pipeline (e.g., during the **`.pre`** stage), create a deployment entity in Rely to represent your pipeline's initiation.
  * **Progressive Updates:** Continue to update this entity with additional information as your pipeline progresses, culminating with a comprehensive update at the end (**`.post`** stage). Ensure consistency by using the same entity ID for all updates.

### **Relevant API Endpoints for Rely Integration**

**Create Entity:**

* Method: **`POST`**
* URL: **`https://magneto.rely.io/api/v1/entities`**

**Update Entire Entity:**

* Method: **`PUT`**
* URL: **`https://magneto.rely.io/api/v1/entities/{id}`**

**Partial Update of an Entity:**

* Method: **`PUT`**
* URL: **`https://magneto.rely.io/api/v1/entities/{id}?patch=true`**
* Note: Only specified properties and relations in the request will be updated.

All available endpoints can be found in our [official documentation](https://docs.rely.io/public-api/overview).

### E.g. 1 Creating a Deployment and Relating it to Gitlab Pipeline that’s ingested by Rely’s Gitlab Plugin

```yaml
rely-create-deployment:
  stage: .pre
  image: docker:24.0.5
  before_script:
    - apk add --no-cache jq yq git curl    # Installing jq, yq, git, curl
  script:
    - |-
      PAYLOAD=$(cat << JSON
      {
        "blueprintId": "deployment",
        "id": "${CI_PROJECT_NAME}-${CI_PIPELINE_ID}",
        "title": "${CI_PROJECT_NAME}-${CI_PIPELINE_ID}",
        "description": "",
        "properties": {},
        "relations": {
          "pipeline": {
            "value": "${CI_PIPELINE_ID}"
          }
        }
      }
      JSON
      )
    - >
      curl -o - -X POST "<https://magneto.rely.io/api/v1/entities>" 
      -H "Authorization: Bearer $PUBLIC_API_TOKEN"
      -H "Content-Type: application/json" 
      -d "$PAYLOAD"
```

### E.g. 2 Updating a specific Service’s OpenAPI schema

```yaml
rely-update-service:
  stage: .pre
  image: docker:24.0.5
  before_script:
    - apk add --no-cache jq yq git curl    # Installing jq, yq, git, curl
  script:
    - |-
      PAYLOAD=$(cat << JSON
      {
        "blueprintId": "service",
        "id": "<your-entity-id>",
        "properties": {
		        "api-schema": "<your-open-api-json-schema>"
        },
      }
      JSON
      )
    - >
      curl -o - -X POST "<https://magneto.rely.io/api/v1/entities/><your-entity-id>/patch=true"  # Update yout entity id in the URL 
      -H "Authorization: Bearer $PUBLIC_API_TOKEN"
      -H "Content-Type: application/json" 
      -d "$PAYLOAD"
```

### E.g. 3 Fleshed-out example for creating a Deployment Entity during Merge Request Pipelines to Main

💡 Some of the native Gitlab variables here are only available for pipelines that run as a result of merge requests

💡 Note that, you can only reference in your update calls properties & relations defined in your data-model in Rely.

```yaml
workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "main"

(...)

rely-create-deployment:
  stage: .pre
  image: docker:24.0.5
  before_script:
    - apk add --no-cache jq yq git curl    # Installing jq, yq, git, curl
  script:
    - |-
      PAYLOAD=$(cat << JSON
      {
        "blueprintId": "deployment",
        "id": "${CI_PROJECT_NAME}-${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}-${CI_PIPELINE_ID}",
        "title": "${CI_PROJECT_NAME}-${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}-${CI_PIPELINE_ID}",
        "description": "",
        "properties": {
          "date": "${CI_PIPELINE_CREATED_AT}",
          "triggered-by": "${GITLAB_USER_NAME}",
          "current-stage": "${CI_JOB_STAGE}",
          "deployment-status": "Running CI pipeline stage: ${CI_JOB_STAGE}",
          "commit-hash": "${CI_COMMIT_SHORT_SHA}",
          "target-branch": "${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}",
          "merge-request-title": "${CI_MERGE_REQUEST_TITLE}",
          "merge-request-link": "${CI_MERGE_REQUEST_PROJECT_URL}/-/merge_requests/${CI_MERGE_REQUEST_IID}",
          "merge-request-description": $(echo "${CI_MERGE_REQUEST_DESCRIPTION}" | jq -Rs .),
          "pipeline-id": "${CI_PIPELINE_ID}",
          "pipeline-link": "${CI_PIPELINE_URL}",
          "created-service-artifact": "<https://europe-west2-docker.pkg.dev/$GCP_PROJECT_ID/rely-docker-images/$CI_PROJECT_NAME:$CI_COMMIT_SHORT_SHA>" 
        },
        "relations": {
          "service": {
            "value": "${CI_PROJECT_NAME}"
          }
        }
      }
      JSON
      )
    - >
      curl -o - -X POST "<https://magneto.rely.io/api/v1/entities>" 
      -H "Authorization: Bearer $PUBLIC_API_TOKEN"
      -H "Content-Type: application/json" 
      -d "$PAYLOAD"
```


# Software Catalog


# Overview and Use Cases

The Software Catalog is at the heart of Rely, serving as a comprehensive collection of an organization's catalogs. These include the service catalog, team catalog, and cloud-resource catalog, among others. It provides a unified view to track and explore information about various entities within the organization.&#x20;

Entities in the catalog are defined by their properties and relationships, and are structured through customizable blueprints. This allows for tailored documentation and management of the software ecosystem.

{% embed url="<https://www.youtube.com/watch?v=NcMTG1vLOuo>" %}

## Use Cases

* **Centralized Information Access:** Developers can easily access a single source of truth for all software-related information, improving efficiency and reducing errors.
* **Information Standardization:** Platform teams can define and manage entities using customizable blueprints. This ensures all relevant attributes and relationships are specified, documented, and maintained through automation, reducing maintenance time and ensuring consistency.


# Usage Guide


# Creating a new Entity

## From the UI

You can create entities of a given type directly from its respective [catalog](/basic-concepts/catalogs).&#x20;

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2F3Nj3SuJmAzhCQvQ8GGQi%2Fimage.png?alt=media&amp;token=fa42ff82-09c4-4d89-8fc9-0e942b628e00" alt=""><figcaption></figcaption></figure>

From here, you can create an entity by:

* Filling in its [metadata](/basic-concepts/entities) fields (title, id, description).
* Or by directly providing a valid [entity descriptor](/basic-concepts/entities#entity-descriptor).

## From the Public API

{% content-ref url="/pages/jYOZZ73s8G5yFymb7dYP" %}
[Entities](/public-api/entities)
{% endcontent-ref %}


# Updating an Entity

## From the UI

## Settings Page

You can manage an entity's content from its settings page.&#x20;

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2Fgbeurfh4wjILtYP8qUO2%2Fimage.png?alt=media&amp;token=a51c1695-f137-4d51-ba62-312a4807b449" alt=""><figcaption></figcaption></figure>

The Settings Page consists of 4 tabs:

* **Properties:** Here, you can view all available data associated with your entity, including metadata, properties, and relations. You can also manage the sources from which this data originates.
* **Sources:** This tab allows you to manage the sources from which data automatically populates this entity. [Multiple sources from plugins can feed data into entities](/basic-concepts/user-blueprints-vs-plugin-blueprints).
* **JSON:** In this tab, you can view and directly edit your [entity descriptor.](/basic-concepts/entities#entity-descriptor)
* **Audit Logs:** This tab enables you to [track changes made to your entity](/software-catalog/usage-guide/tracking-entity-changes) over time.

## Manually Configuring Values

{% hint style="info" %}
Only fields that have their source set to "Manual" can be manually edited, both through the UI and the public API. Fields with other sources are automatically updated by [automation rules](/basic-concepts/actions-and-automations/automation-rules).
{% endhint %}

From the properties tab, hoover over a given metadata, property or relation field for the edition button to become visible. The edition flow varies according to the field's [data-type](/basic-concepts/property-data-types).&#x20;

{% embed url="<https://drive.google.com/file/d/1ZMdSRh92uJ0d2J0XBFmIVy_Y-MVDyIM-/view?usp=drive_link>" %}

Alternatively you can also directly edit the [entity descriptor](/basic-concepts/entities#entity-descriptor).

{% hint style="info" %}
Changing the entity directly can sometimes be useful for [troubleshooting](/software-catalog/troubleshooting) purposes.&#x20;
{% endhint %}

{% embed url="<https://drive.google.com/file/d/1DXnVambkYnFtMSqD9F08O0Y89aRpd760/view?usp=drive_link>" %}

## Configuring Automated Value Assignment

ou might want to configure certain fields within your entity to automatically receive and update data from external sources that integrate with Rely through its plugins.

Entities can have sources that automatically update it, these can be:

* [Automation Rules](/basic-concepts/actions-and-automations/automation-rules)
* [Plugin Entities](/basic-concepts/user-blueprints-vs-plugin-blueprints)

You can manage the sources available to your entity in the sources tab in the [entity settings page](#settings-page), or by directly manipulating the [entity descriptor](/basic-concepts/entities#entity-descriptor).

{% embed url="<https://drive.google.com/file/d/1wMr3ELoILvZlQ6Zc09b1sUYM2x7xDYX8/view?usp=drive_link>" %}

{% hint style="info" %}
Automation Rules declare themselves as an entity's source when they perform updates to it.&#x20;
{% endhint %}

## From the Public API

{% content-ref url="/pages/jYOZZ73s8G5yFymb7dYP" %}
[Entities](/public-api/entities)
{% endcontent-ref %}


# Tracking Entity Changes

## From the UI

You can track the changes that have been performed to an entity over time via its audit logs which are accessible in its own tab in the [entity settings page.](/software-catalog/usage-guide/updating-an-entity#settings-page)

{% hint style="info" %}
Note that these logs are only retained for a period of 7 days.
{% endhint %}

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FBNVMtMeussm9nvfeRiSW%2Fimage.png?alt=media&amp;token=4e5e04ce-0431-42a4-9bad-ffe1f88823d6" alt=""><figcaption></figcaption></figure>

## From the Public API

{% content-ref url="/pages/2M1M6xS8JAqJ1ts2oq3F" %}
[Audit Logs](/public-api/audit-logs)
{% endcontent-ref %}


# Customizing an Entity's Page

## From the UI

You can customise an entity's details page with new dashboard tabs.&#x20;

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2F2DSExgWa9EfNYCirnz8N%2Fimage.png?alt=media&amp;token=b918508d-72e5-4bfe-a23a-10a34976b6a8" alt=""><figcaption></figcaption></figure>

### Dashboard Tabs

You can customise your dashboard by hitting the Edit Dashboard button.&#x20;

{% hint style="info" %}
Unlike customizable homepages tailored to each user, entity dashboards are uniform for all members of the organization. When configuring these dashboards, remember that any changes will affect the entire company.
{% endhint %}

{% embed url="<https://drive.google.com/file/d/1EcV17Ha7dxaSbgARUPpJysqMOonQ7pvQ/view?usp=drive_link>" %}

There are three types of widgets that you can add to your dashboards:

1. **Property Group**: Displays a list of an entity's metadata, properties, and relations.
2. **Property Value**: Focuses on a specific metadata, property, or relation.
3. **Table**: Displays a catalog as a widget.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FSOC2jTgmzGHHSFkT9gJO%2Fimage.png?alt=media&amp;token=e7499417-d67f-4bc2-9802-e891ef29bc6b" alt=""><figcaption></figcaption></figure>

## From the Public API

{% content-ref url="/pages/tYhk0iNq7FYPBgNEX3cO" %}
[Dashboards & Views](/public-api/dashboards-and-views)
{% endcontent-ref %}


# Customizing a Catalog

## From the UI

You can use the control zones within a [catalog](/basic-concepts/catalogs)'s table component to:

* Choose which columns to display
* Re-order columns&#x20;
* Group entities by one or more specific fields
* Sort data by any field
* Apply text filters

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2Fm0Nk2KYQciyG8JzqFPno%2Fimage.png?alt=media&amp;token=581b6a72-ea97-47b7-b162-57af35e3bafb" alt=""><figcaption></figcaption></figure>

You can drag-and-drop a collumn to the control zone to apply group-by clauses on the table.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FeJCjC20qktelLUmYVL0A%2FScreenshot%202024-05-21%20at%2021.21.41.png?alt=media&amp;token=d3ca062b-fc93-4bd2-935d-acc576b5729c" alt=""><figcaption></figcaption></figure>

You can save a view configuration to **all users within your organisation** by pressing the save-view button.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FuVdwkSFLYyBEDOYYNuqt%2Fimage.png?alt=media&amp;token=87147db5-d679-44ec-bdd0-296ecc7bb046" alt=""><figcaption></figcaption></figure>

## From the Public API

{% content-ref url="/pages/tYhk0iNq7FYPBgNEX3cO" %}
[Dashboards & Views](/public-api/dashboards-and-views)
{% endcontent-ref %}


# Creating a new Blueprint & Catalog

## From the UI

Each [blueprint](/basic-concepts/blueprints) has their own [catalog](/basic-concepts/catalogs) so by creating a new blueprint you're automatically adding a new catalog tab to your software catalog.

You can manage your blueprints via:

* The [Data Model Builder](/software-catalog/usage-guide/updating-a-blueprint#from-the-data-model-builder) for a visual graph-based representation of how all your blueprints relate to one another
* Or by directly accessing the [blueprint descriptors](/basic-concepts/blueprints#blueprint-descriptor).

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FP8p1TJcwiSNT3JsOKL47%2Fimage.png?alt=media&amp;token=9b5e4d06-cbb8-490f-ac5e-69bd551c70f0" alt=""><figcaption></figcaption></figure>

From here you can create a blueprint by:

* Filling in its [metadata](/basic-concepts/blueprints) fields (title, id, description)
* Or by directly providing a valid [blueprint descriptor](/basic-concepts/blueprints#blueprint-descriptor)

## From the Public API

{% content-ref url="/pages/omhxzZx0bXN1GJPiJZLO" %}
[Blueprints](/public-api/blueprints)
{% endcontent-ref %}


# Updating a Blueprint

## From the UI

You can manage your [data-model](/basic-concepts/data-model) and all its [blueprints](/basic-concepts/blueprints) via:

* The [data model builder](#from-the-data-model-builder) for a visual graph-based interface
* Or by directly manipulating [blueprint descriptors](#from-the-blueprint-descriptor).

### From the Data Model Builder

&#x20;The [Data Model Builder](/basic-concepts/data-model) is the most visually appealing of managing your blueprints, but it's not the most powerful one.

{% hint style="warning" %}
From the builder you are unable to:

* Edit the blueprint's title.
* Edit a property's metadata or data-type.
* Edit a relation's title or [overall nature](/basic-concepts/blueprints#blueprint-descriptor) (e.g. its target blueprint or its cardinality between one-to-one and one-to-many).

For these operations, you need to perform updates directly on the [blueprint's descriptor](#from-the-blueprint-descriptor).
{% endhint %}

{% hint style="danger" %}
Changing a blueprint's ID is impossible across the product, regardless of whether via the UI or API. This is a measure meant to prevent issues related to data misalignment.
{% endhint %}

To see the content of a Blueprint, click on its node in the graph view.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FPK26bpqx3kcyYR4x7psl%2Fimage.png?alt=media&amp;token=162dce29-dce1-4cdc-a836-e62847ced05a" alt=""><figcaption></figcaption></figure>

From here, you can create new properties and relations.&#x20;

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2F5k2nTPpEexGJ2i5eKp1R%2Fimage.png?alt=media&amp;token=f15521cb-cee1-45c6-bfb6-7af00659038b" alt="" width="375"><figcaption></figcaption></figure>

From existing relations, you can establish [reference properties](/basic-concepts/property-data-types#reference-properties).

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FZWpSo6DMjkzx1usZQEG8%2Fimage.png?alt=media&amp;token=a22a766a-2bdd-4213-b558-62464f0f2304" alt="" width="375"><figcaption></figcaption></figure>

You can also delete existing properties and relations.

{% hint style="danger" %}
Deleting a property or drastically changing its type in the blueprint can cause entities created from it to enter a conflict state that you'll need to resolve manually, see [troubleshooting](/software-catalog/troubleshooting).
{% endhint %}

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2F8oTMUJ0ztC8mFQzjrWts%2Fimage.png?alt=media&amp;token=4de4a252-6f22-4bbb-b362-eb0e0972f28a" alt="" width="375"><figcaption></figcaption></figure>

You can also edit a blueprint's icon or deleting the blueprint.

{% hint style="danger" %}
Deleting a blueprint can cause other blueprints that have relations to it and its respective entities to enter a conflict state that you'll need to resolve manually, see [troubleshooting](/software-catalog/troubleshooting).
{% endhint %}

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FTs2rdUtWl7WlLbZZggac%2Fimage.png?alt=media&amp;token=681cc8e5-3583-46f9-916a-7023b7523b8a" alt="" width="375"><figcaption></figcaption></figure>

From a blueprint card you can also directly access the [blueprint's descriptor](/basic-concepts/blueprints#blueprint-descriptor) for more powerful manipulation capabilities.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2F3etr114pYPUpn0zvx2Uu%2Fimage.png?alt=media&amp;token=915676bd-482f-4bf2-9fe9-1931c50bd7dd" alt="" width="375"><figcaption></figcaption></figure>

### From the Blueprint Descriptor

&#x20;Directly manipulating the [blueprint descriptors](/basic-concepts/blueprints#blueprint-descriptor) is the most powerful way of managing your blueprint, but it also requires deeper technical knowledge.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FpVBdtrBd0Jg1MRZwiUOC%2Fimage.png?alt=media&amp;token=de414b70-29f3-4eb3-8610-e66391a2568a" alt=""><figcaption></figcaption></figure>

From here, you can customise every aspect regarding your blueprint, like:

* Editing the blueprint's metadata (except for the ID).
* Editing properties' metadata and [data-type](/basic-concepts/property-data-types).
* Editing relations' metadata and [overall nature](/basic-concepts/blueprints#blueprint-descriptor) (e.g. its target blueprint or its cardinality between one-to-one and one-to-many).

Some considerations:

{% hint style="danger" %}
Changing a blueprint's ID is impossible across the product, regardless of whether via the UI or API. This is a measure meant to prevent issues related to data misalignment.
{% endhint %}

{% hint style="danger" %}
Deleting a property or drastically changing its type in the blueprint can cause entities created from it to enter a conflict state that you'll need to resolve manually, see [troubleshooting](/software-catalog/troubleshooting).
{% endhint %}

{% hint style="danger" %}
Deleting a blueprint can cause other blueprints that have relations to it and its respective entities to enter a conflict state that you'll need to resolve manually, see [troubleshooting](/software-catalog/troubleshooting).
{% endhint %}

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2Fsv81sKhFKdLA7wuqf3a2%2Fimage.png?alt=media&amp;token=8e86d6ff-e3db-4b11-a9c2-f5d5e213f094" alt=""><figcaption></figcaption></figure>

## From the Public API

{% content-ref url="/pages/omhxzZx0bXN1GJPiJZLO" %}
[Blueprints](/public-api/blueprints)
{% endcontent-ref %}


# Tracking Blueprint Changes

## From the UI

You can track the changes that have been performed to a blueprint over time via its audit logs.

{% hint style="info" %}
Note that these logs are only retained for a period of 7 days.
{% endhint %}

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FFTv0L2ZkjwLJHTdsChCQ%2Fimage.png?alt=media&amp;token=05fc6040-21dc-4be4-96c3-b8a181cd361f" alt=""><figcaption></figcaption></figure>

## From the Public API

{% content-ref url="/pages/2M1M6xS8JAqJ1ts2oq3F" %}
[Audit Logs](/public-api/audit-logs)
{% endcontent-ref %}


# Relevant Guides

<table data-view="cards"><thead><tr><th>Relevant Guides</th></tr></thead><tbody><tr><td><a href="/guides-and-tutorials/enhancing-deployment-visibility-through-gitlab-pipelines-and-relys-api">Enhancing Deployment Visibility through Gitlab Pipelines and Rely's API</a></td></tr></tbody></table>


# Troubleshooting

## Common Issues When Creating and Updating Entities

### Entity IDs

* **Format Requirements:** Entity IDs must be in lowercase and should not contain special characters.&#x20;
* **Immutability:** Once an entity ID is created, it cannot be updated. If a change is necessary, the entity must be recreated with the desired ID.
* **Uniqueness:** Each entity ID must be unique across all entities within the catalog to prevent identification errors.

### Property Values

* **Data Type Compliance:** Property values must match the data type specified in the blueprint. The system performs validations on these values to ensure they adhere to the defined `type` and `format` arguments in the blueprint.
* **Non-nullable Values:** Property values cannot be set to `null`. If you need to remove a property value, you should delete the entire key-value pair from the entity descriptor.

### Relations

* **Relation Types:** Relations in a blueprint are defined as either 1:1 or 1:many. In the entity descriptor, this is reflected by setting relation values to either a single entity ID or a list of entity IDs.
* **Invalid States:** If drastic changes are made to a blueprint (e.g., removing properties or relations that are already utilized in entities), your entity might enter an invalid state. It’s required to update all related entities to align with the new blueprint structure to maintain system integrity.&#x20;

{% hint style="info" %}
If you need to propagate changes to several entities in you software catalog, feel free to leverage the python script provided bellow.
{% endhint %}

##

## Common Issues When Creating and Updating Blueprints

### Blueprint IDs

* **Format Requirements:** Blueprint IDs must be lowercase and devoid of special characters to maintain system consistency.
* **Immutability:** Blueprint IDs cannot be updated after creation. To modify an ID, a new blueprint must be created with the correct ID, and the old blueprint must be deprecated.
* **Uniqueness:** Each blueprint ID must be unique across all blueprints to ensure accurate references and dependencies within the catalog.

## Reach Out to Customer Support

If you encounter any issues that you're unable to resolve on your own, please don't hesitate to contact our support team at `support@rely.io`.&#x20;

Additionally, if you would like to discuss a specific use-case you're targeting, feel free to [book a session with one of our experts](https://calendar.app.google/fHWH3to58EcSqLdh8) to brainstorm and gain further insights.


# Scorecards


# Overview and Use Cases

Scorecards in Rely.io allow you to establish consistent standards for your services, helping you answer critical questions about your application as a whole. They simplify complexity and reduce firefighting, giving developers more time to focus on building new features. By customizing scorecards to reflect your organization’s priorities, you can ensure alignment on what matters most.

**Why Scorecards?** Operational efficiency has always been a priority for engineering teams, but with tightening budgets, it’s now essential. Bugs, security incidents, and unreliable services can slow your team down and divert resources from strategic initiatives. Rely.io helps you minimize these distractions by setting clear, measurable standards for your services, so you can focus efforts where they’re most needed and spend less time putting out fires.

**How Scorecards Work** -> Scorecards automatically assess entities against predefined criteria and assign a performance rank — bronze, silver, or gold — based on these evaluations. Each rank comes with specific rules, leveraging properties from across your tool stack to measure compliance and identify areas for improvement. For example:

* Are teams meeting production readiness standards?
* Are services aligned with DORA metrics and operational best practices?
* Are on-call escalation policies and runbooks documented?

**Drive engineering xxcellence** with Rely.io's Scorecards, you can define and track KPIs and standards across various dimensions like quality, production readiness, and team productivity, fostering a culture of engineering excellence. By making these metrics visible, engineering leaders can:

* **Promote best practices**: Easily share and track the adoption of organizational standards such as production readiness, operational maturity, and observability.
* **Encourage continuous improvement**: Use Scorecards to assess, rank, and improve the maturity of services across teams, providing a clear path toward achieving top performance.
* **Streamline compliance monitoring**: Automate compliance checks and gain visibility into how well services align with security, operational, and quality standards.

Watch a quick overview on how to use scorecards in Rely.io to define and track best practices across your organization 👇

{% embed url="<https://www.youtube.com/watch?v=9iCQpH_v81Y>" %}

## Leaderboards

Once you set up a scorecard, you're already halfway there. The other half is ensuring teams and team members actually follow the guidance and best practices that the scorecards are tracking.

With this in mind, [Rely.io](http://rely.io/) created leaderboards. These leaderboards not only let engineers and team leads know how their teams are performing but also allow them to compare against other teams. This introduces gamification into the product, driving people to focus more on achieving the defined goals. Let's face it, no one wants to be last, right?

## Use Cases

Organizations use scorecards in various situations, but their main purpose is to track the implementation and execution of strategic goals. Here are a few examples of how we've seen customers using them.

* **Compliance Monitoring:** Platform teams can set compliance targets and automatically evaluate entities against these standards, ensuring adherence to best practices.
* **Performance Tracking:** Entities are ranked based on predefined criteria, allowing teams to track performance and identify areas for improvement.
* **Standard Enforcement:** By defining rules and ranks, platform teams can enforce organizational standards and practices, fostering a culture of quality and reliability.


# Usage Guide


# Creating a Scorecard

When users create a new account in [Rely.io](http://rely.io/) and set up core plugins (Git Provider and Incident Management Provider), they'll see default scorecards and metrics in their account. This helps users get started quickly.

Users also have the option to create their own scorecards that fit their specific business objectives. There are two ways to create scorecards: through the user interface or by using the Public API.

## From the UI

You can create a scorecard from the scorecards catalog by directly providing a valid [scorecard descriptor](/basic-concepts/scorecards#scorecard-descriptor).

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FARpluTELJ6nsmRGI2yKG%2Fscorecards-create.gif?alt=media&amp;token=d607ece8-ac50-4790-a32b-c3d275c5e363" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
You can **only** create scorecard rules that reference **properties that exist in the blueprint** the scorecard applies to.\
\
Make sure the blueprint descriptor is compliant with whatever you're trying to set before submitting the scorecard.
{% endhint %}

Once you create a scorecard, an automation process will automatically assess the compliance of various entities against the specified ranks and rules in the scorecard. Typically, you can expect the results to arrive within a few seconds.

{% hint style="info" %}
Entities that don't comply with the lowest rank (bronze), will be shown as "No Rank"
{% endhint %}

## From the Public API

You can create scorecards from the Public API by using the endpoint listed below.

{% content-ref url="/pages/TYsaooLVFLywVwLXo4my" %}
[Scorecards](/public-api/scorecards)
{% endcontent-ref %}

{% hint style="info" %}
Remember that in order to call Rely.io Public API you need to authenticate before. If this is your first time doing it refer to the [official docs](/public-api).
{% endhint %}


# Updating a Scorecard

As organizations evolve and get more complex so will the metrics that you need to look at to ensure compliance with business objectives.&#x20;

There will be a point in time where you will need to update your scorecards. You can do it in two different ways: From the UI and from the Public API.

## From the UI

You can access a scorecard's details page from the scorecard catalog by clicking one of its rows.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2F82bucad5W581UAnpKMiw%2Fscorecards-list-docs.gif?alt=media&amp;token=445c9ca2-f71d-493a-a45f-e612d14cb266" alt=""><figcaption></figcaption></figure>

From here, you can update a scorecard by directly manipulating the [scorecard descriptor](/basic-concepts/scorecards#scorecard-descriptor) in the code tab.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FDyz9p1GJIfbNLDiisVKT%2Fscorecards-update-json.png?alt=media&amp;token=c7cf856a-5490-4475-bd32-96251cd753c6" alt=""><figcaption></figcaption></figure>

Once you update a scorecard, an automation process will automatically assess the compliance of various entities against the changes in the scorecard. Typically, you can expect the results to adapt within a few seconds.

{% hint style="info" %}
Entities that don't comply with the lowest rank (bronze), will be shown as "No Rank"
{% endhint %}

## From the Public API

All scorecard descriptors are JSON files that you might want to keep in a repository next to your code. If you follow that approach then using Rely.io Public API might not be a bad option. You can use the following Scorecards endpoint to do so.

{% content-ref url="/pages/TYsaooLVFLywVwLXo4my" %}
[Scorecards](/public-api/scorecards)
{% endcontent-ref %}

{% hint style="info" %}
Remember that in order to call Rely.io Public API you need to authenticate before. If this is your first time doing it refer to the [official docs](/public-api).
{% endhint %}


# Evaluating Performance

At this point in time you already setup your own scorecards and Rely.io is collecting metrics automatically for you. But how can you see the scorecard results?&#x20;

## From the UI

You can access a scorecard's details page from the scorecard catalog by clicking one of its rows.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FcDo2QFrpNHZZgVbhWiPf%2Fscorecards-list-docs.gif?alt=media&amp;token=3efc831e-5b8d-4d2b-9e42-0d6bd297b4ab" alt=""><figcaption></figcaption></figure>

From this view, you can access the leaderboard to assess:&#x20;

* The rank of all your entities to which the scorecard is applied.
* The compliance of each entity with each rule in the scorecard.
* The actual values from each entity that are compared against the threshold specified in each rule.

{% hint style="info" %}
Entities that don't comply with the lowest rank (bronze), will be shown as "No Rank"
{% endhint %}

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FqXgwTCUObeK7QWCTXI0u%2Fscorecards-leaderboard.png?alt=media&amp;token=91318c0f-caf0-49c1-8cf9-a2ea246509fb" alt=""><figcaption></figcaption></figure>

## From the Public API

Using Rely.io Public API to evaluate performance is important if you are building an integration with third-party tools or platforms, or building custom reports in an automated way. To do so, refer to the following REST API endpoint documentation.

{% content-ref url="/pages/TYsaooLVFLywVwLXo4my" %}
[Scorecards](/public-api/scorecards)
{% endcontent-ref %}

{% hint style="info" %}
Remember that in order to call Rely.io Public API you need to authenticate before. If this is your first time doing it refer to the [official docs](/public-api).
{% endhint %}


# Scorecard Examples

Scorecards allow you to communicate and make progress on what is important to your organization.

In this section, we’re providing examples for scorecards you can create to track and promote the adoption of engineering excellence standards. \
These scorecards can span from any type of standard across the software delivery lifecycle, from engineering efficiency (e.g. DORA & SPACE metrics) to operational, security and even development maturity standards.

Each example includes:

* **An overview** of the scorecard's focus areas.
* **The requirements** for each level of maturity (Bronze, Silver, and Gold).
* **The code template** to implement these scorecard in Rely.io.


# Production Readiness Scorecard Example

## Production readiness overview

Production readiness is about ensuring your software is secure, reliable, and fully observable for operational use. It minimizes downtime, improves user experiences, and reduces the chance of critical failures in a live environment.

Achieving production readiness involves setting up cross-functional standards like testing, monitoring, documentation, code reviews, observability, security controls, and deployment workflows, often across different infrastructure like AWS, GitHub, and Kubernetes. However, keeping up with the velocity of modern software development is a challenge. Many organizations still rely on spreadsheets, wikis, Git repositories, or project management software to manage this process.

But production readiness isn’t a “one-time” check; it’s an ongoing process. With software components constantly evolving, it’s essential to ensure that they remain production-ready over time. That means having a framework in place to assess ongoing health, check for functionality, latency, and error rates, and monitor adherence to standards. This allows teams to continuously align with best practices and reduce the burden on developers.

## Key Elements to Track for Production Readiness

**🥇 Gold Tier Requirements:**

* **Code Coverage ->** Achieve at least 90% code coverage to ensure comprehensive testing.
* **Critical Issues ->** No open critical issues in tracking systems like Jira.
* **Vulnerabilities ->** Zero known vulnerabilities identified by tools like SonarQube.
* **Alerting Configuration ->** System alerts set up for monitoring key metrics.
* **Escalation Policies ->** Defined on-call escalation policies with at least two levels.
* **Secure Design Reviews ->** Conduct periodic reviews for secure design validation.
* **Availability and Latency SLOs ->** Meet set SLO targets for availability and latency consistently.
* **Traffic KPIs ->** Track key traffic metrics to monitor performance in real-time.
* **P99 Latency Tracking ->** Maintain logs for P99 latency metrics.
* **Error Rate Tracking ->** Ensure error tracking is enabled to capture incidents in real-time.

**🥈 Silver Tier Requirements:**

* **Health Dashboards ->** Have dashboards for real-time system health visibility.
* **Code Coverage ->** Maintain code coverage of at least 75%.
* **Advanced Security ->** Enable advanced security scanning (e.g., Dependabot, CodeQL).
* **Rollback Documentation ->** Document rollback processes for quick recovery.
* **Runbooks ->** Provide runbooks for all critical processes.
* **Observability Integration ->** Ensure observability tools are integrated as sources for each service.

**🥉Bronze Tier Requirements:**

* **Git Ignore ->** Confirm a `.gitignore` file is present in each repository.
* **Git Integration ->** Integrate the Git provider as a data source in the catalog.
* **Incident Management Integration ->** Integrate with incident management tools to handle issues.
* **Peer Reviews for PRs ->** Require peer reviews for all pull requests.
* **Recent Deployments ->** Track and log recent deployments.
* **Owner Assignment ->** Ensure at least one owner is assigned to each service.
* **On-Call Definition ->** Establish an on-call rotation for handling incidents.
* **README File ->** Ensure that each repository includes a README for quick reference.
* **SLOs for Availability and Latency ->** Define SLOs for key metrics such as availability and latency.

By following these tiers, you can ensure that your services remain production-ready and avoid manual processes to keep software aligned with ongoing standards. With a framework in place, you’ll not only meet today’s needs but also be prepared to scale and adapt as software evolves.

## Example production readiness scorecard code definition&#x20;

<details>

<summary>Example production readiness scorecard code definition</summary>

```json
{
  "id": "service-production-readiness",
  "title": "Production Readiness Checklist",
  "description": "This checklist contains points that must be satisfied during implementation and verified prior to release. Please note that all these items must still be satisfied post release.",
  "isActive": true,
  "blueprintId": "service",
  "ranks": [
    {
      "id": "bronze",
      "rules": [
        {
          "id": "readme-available",
          "title": "Readme is available",
          "description": "The readme property for this service is being populated from the git provider.",
          "conditions": [
            {
              "field": "data.properties.readme",
              "operator": "like",
              "value": "_%"
            }
          ]
        },
        {
          "id": "required-peer-reviews-for-prs",
          "title": "Pull requests require at least 1 peer review",
          "description": "The repo of this service is configured to have at least 1 peer review mandatory to approve pull requests. Validated by assessing whether the property numRequiredApprovals of this service is greater than 1.",
          "conditions": [
            {
              "field": "data.properties.numRequiredApprovals",
              "operator": "gte",
              "value": 1
            }
          ]
        },
        {
          "id": "recent-deployments",
          "title": "At least one deployment this month?",
          "description": "Validates whether there has been at least one deployment in this service since the start of the month.",
          "conditions": [
            {
              "field": "data.calculationProperties.deploymentCountProd.1m.value",
              "operator": "gte",
              "value": 1
            }
          ]
        },
        {
          "id": "owner-is-assigned",
          "title": "Service Owner is Assigned",
          "description": "The service owner team is specified",
          "conditions": [
            {
              "field": "SELECT (s.relations->'owner'->'value' is not null)::integer AS num_owners FROM entities s WHERE s.blueprintid = 'service' AND s.id = '{{ data.id }}'",
              "expression": true,
              "operator": "gte",
              "value": 1
            }
          ]
        },
        {
          "id": "on-call-defined",
          "title": "At least one person is on call",
          "description": "The property currentOnCalls has at least one person assigned to this service.",
          "conditions": [
            {
              "field": "data.properties.currentOnCalls",
              "operator": "like",
              "value": "[_%]"
            }
          ]
        }
      ]
    },
    {
      "id": "silver",
      "rules": [
        {
          "id": "monitoring-dashboards-defined",
          "title": "Monitoring dashboards are defined",
          "description": "At least one link was added to the monitoring dashboards url property of this service.",
          "conditions": [
            {
              "field": "data.properties.monitoringDashboards",
              "operator": "like",
              "value": "[_%]"
            }
          ]
        },
        {
          "id": "rollback-process-is-documented",
          "title": "The rollback process is documented",
          "description": "At least one link was added to the rollback process url property of this service.",
          "conditions": [
            {
              "field": "data.properties.rollbackProcess",
              "operator": "like",
              "value": "_%"
            }
          ]
        },
        {
          "id": "code-coverage-ge-75",
          "title": "Code coverage >= 75%",
          "description": "The code for this service's repo is greater or equal to 85%",
          "conditions": [
            {
              "field": "data.properties.codeCoverage",
              "operator": "gte",
              "value": 75
            }
          ]
        },
        {
          "id": "runbooks-are-available",
          "title": "There are one or more runbooks available",
          "description": "At least one link was added to the runbooks url property of this service.",
          "conditions": [
            {
              "field": "data.properties.runbooks",
              "operator": "like",
              "value": "[_%]"
            }
          ]
        }
      ]
    },
    {
      "id": "gold",
      "rules": [
        {
          "id": "code-coverage-ge-90",
          "title": "Code coverage >= 90%",
          "description": "The code for this service's repo is greater or equal to 85%",
          "conditions": [
            {
              "field": "data.properties.codeCoverage",
              "operator": "gte",
              "value": 90
            }
          ]
        },
        {
          "id": "no-critical-jira-issues",
          "title": "No critical jira issues",
          "description": "All critical Jira issues with priority in 'P0' and 'P1 have their status in 'Done', 'Resolved' or 'Closed'.",
          "conditions": [
            {
              "field": "data.properties.openCriticalJiraIssues",
              "operator": "eq",
              "value": 0
            }
          ]
        },
        {
          "id": "open-vulnerabilities",
          "title": "No open vulnerabilities",
          "description": "There is no known vulnerability assigned to this service with their status not in 'Resolved' or 'Closed'.",
          "conditions": [
            {
              "field": "data.properties.openVulnerabilities",
              "operator": "eq",
              "value": 0
            }
          ]
        },
        {
          "id": "alerting-tool-defined",
          "title": "Alerting tool is configured",
          "description": "At least one link was added to the alertingTool url property of this service. The link should redirect to the alerting tool filtered by the alerts assigned to this service.",
          "conditions": [
            {
              "field": "data.properties.alertingTools",
              "operator": "like",
              "value": "_%"
            }
          ]
        },
        {
          "id": "on-call-escalation-policies",
          "title": "On call escalation policies >= 2",
          "description": "At least 2 levels are defined in the escalation policy, so that if the first on-call does not acknowledge within the defined time frame, there is a backup.",
          "conditions": [
            {
              "field": "SELECT coalesce(sum(jsonb_array_length(coalesce(s.properties->'escalationPolicies'->'url', '[]'))), 0) AS num_urls FROM entities s WHERE s.blueprintid = 'service' AND s.id = '{{ data.id }}'",
              "expression": true,
              "operator": "gte",
              "value": 2
            }
          ]
        },
        {
          "id": "secure-by-design-review",
          "title": "Secure by Design Review",
          "description": "Has a secure by design review been conducted? This validates whether the last design review by property of this service has been assigned to someone.",
          "conditions": [
            {
              "field": "data.properties.lastDesignReviewBy",
              "operator": "like",
              "value": "_%"
            }
          ]
        }
      ]
    }
  ],
  "medianRank": "noRank"
}
```

</details>


# DORA Metrics Scorecard Example

## DORA Metrics Overview

The DORA (DevOps Research and Assessment) metrics are a set of key performance indicators used to measure the efficiency and effectiveness of your engineering team’s delivery capabilities. These metrics help teams track their ability to deliver software quickly, with high quality, and to recover from issues swiftly. By implementing DORA metrics, organizations can reduce downtime, improve deployment speeds, and gain visibility into the software development lifecycle.

DORA metrics specifically focus on four main areas:

1. **Deployment Frequency** - How often your organization deploys changes.
2. **Lead Time for Changes** - The time it takes from code commit to release.
3. **Mean Time to Recover (MTTR)** - The average time it takes to recover from a failure.
4. **Change Failure Rate** - The percentage of deployments causing issues.

Each tier in the DORA metrics scorecard aligns with levels of performance for these metrics, helping your organization target best practices for continuous delivery.

## Key Elements to Track for DORA Performance

Each performance level in the DORA framework corresponds to market benchmarks identified by the DORA team in their 2021 *Accelerate State of DevOps* report, representing the different levels of performance and their alignment with industry benchmarks: elite, high and medium performers.

**🏅 Gold Tier - Elite Performers**

* **Deployment Frequency ->** More than 20 deployments per month (multiple times per day).
* **Lead Time for Changes ->** Less than 24 hours to move changes from commit to production.
* **Mean Time to Recover ->** Incident resolution time averages less than one hour.
* **Change Failure Rate ->** Less than 5% of changes result in downtime or service degradation.
* **Failed Deployment Recovery Time ->** Time to recover from a failed deployment averages less than one hour.

**🥈 Silver Tier - High Performers**

* **Deployment Frequency ->** At least five deployments per month (around once a week).
* **Lead Time for Changes ->** Between one day and one week to move changes from commit to production.
* **Mean Time to Recover ->** Average resolution time of less than 24 hours.
* **Change Failure Rate ->** Less than 15% of changes lead to downtime or service degradation.
* **Failed Deployment Recovery Time ->** Recovery time from failed deployments averages less than one day.

**🥉 Bronze Tier - Medium Performers**

* **Deployment Frequency ->** At least one deployment per month.
* **Lead Time for Changes ->** Between one week and one month to move changes from commit to production.
* **Mean Time to Recover ->** Average resolution time of less than one week.
* **Change Failure Rate ->** Less than 30% of changes lead to downtime or service degradation.
* **Failed Deployment Recovery Time ->** Recovery time from failed deployments averages less than one week.

## Example DORA metrics scorecard code definition&#x20;

<details>

<summary>Example DORA metrics scorecard code definition</summary>

```json
{
  "id": "team-dora-metrics-scorecard",
  "title": "Team DORA Metrics Benchmarks",
  "description": "DORA metrics remain the most asked about framework for measuring developer productivity. This scorecard is provided by Rely.io to help you assess how your team is faring against the benchmarks of 100s of other companies. After analyzing survey data from 31,000 software professionals worldwide collected over a period of six years, the DORA team identified four key metrics to help DevOps and engineering leaders better measure software delivery efficiency: Deployment frequency, Lead time for changes, Mean time to recovery (now Failed Deployment Recovery Time), Change failure rate.",
  "isActive": true,
  "blueprintId": "team",
  "ranks": [
    {
      "id": "bronze",
      "rules": [
        {
          "id": "deployment-frequency-medium-performers",
          "title": "At least one deployment this month?",
          "description": "Validates whether there has been at least one deployment in this service since the start of the month.",
          "conditions": [
            {
              "field": "data.calculationProperties.deploymentCountProd.1m.value",
              "operator": "gte",
              "value": 1
            }
          ]
        },
        {
          "id": "lead-time-for-change-medium-performers",
          "title": "Lead time for changes in prod is less than 1 month since the start of the month",
          "description": "Lead Time for Changes (LTC) is the amount of time between a commit and production. LTC indicates how agile your team is—it not only tells you how long it takes to implement changes, but how responsive your team is to the ever-evolving needs of end users.",
          "conditions": [
            {
              "field": "data.calculationProperties.leadTimeForChangesProd.1m.value",
              "operator": "lt",
              "value": 720
            }
          ]
        },
        {
          "id": "mean-time-to-resolve-medium-performers",
          "title": "Mean time to resolve is less than 1 week since the start of the month",
          "description": "Average time to resolve incidents that have been closed in the past 24 hours for a specific service, including unresolved incidents since their start.",
          "conditions": [
            {
              "field": "data.calculationProperties.meanTimeToResolve.1m.value",
              "operator": "lt",
              "value": 168
            }
          ]
        },
        {
          "id": "change-failure-rate-medium-performers",
          "title": "Change failure rate is less than 30% since the start of the month",
          "description": "Change Failure Rate (CFR) is the percentage of releases that result in downtime, degraded service, or rollbacks, which can tell you how effective your team is at implementing changes. This metric is also critical for business planning as repeated failure and fix cycles will delay launch of new product initiatives.",
          "conditions": [
            {
              "field": "data.calculationProperties.changeFailureRate.1m.value",
              "operator": "lt",
              "value": 30
            }
          ]
        },
        {
          "id": "failed-deployment-recovery-time-medium-performers",
          "title": "Failed deployment recovery time is less than 1 week since the start of the month",
          "description": "FDRT is the amount of time it takes your team to restore service when there’s a service disruption as a result of a failed deployment, like an outage. This metric offers a look into the stability of your software, as well as the agility of your team in the face of a challenge.",
          "conditions": [
            {
              "field": "data.calculationProperties.failedDeploymentRecoveryTime.1m.value",
              "operator": "lt",
              "value": 168
            }
          ]
        }
      ]
    },
    {
      "id": "silver",
      "rules": [
        {
          "id": "deployment-frequency-high-performers",
          "title": "Deployed at least 5 times to production since the start of the month",
          "description": "Deployment Frequency (DF) is how often you ship changes, how consistent your software delivery is. This enables your organization to better forecast delivery timelines for new features or enhancements to end user favorites.",
          "conditions": [
            {
              "field": "data.calculationProperties.deploymentCountProd.1m.value",
              "operator": "gte",
              "value": 5
            }
          ]
        },
        {
          "id": "lead-time-for-change-high-performers",
          "title": "Lead time for changes in prod is less than 1 week since the start of the month",
          "description": "Lead Time for Changes (LTC) is the amount of time between a commit and production. LTC indicates how agile your team is—it not only tells you how long it takes to implement changes, but how responsive your team is to the ever-evolving needs of end users.",
          "conditions": [
            {
              "field": "data.calculationProperties.leadTimeForChangesProd.1m.value",
              "operator": "lt",
              "value": 168
            }
          ]
        },
        {
          "id": "mean-time-to-resolve-high-performers",
          "title": "Mean time to resolve is less than 24 hours since the start of the month",
          "description": "Average time to resolve incidents that have been closed in the past 24 hours for a specific service, including unresolved incidents since their start.",
          "conditions": [
            {
              "field": "data.calculationProperties.meanTimeToResolve.1m.value",
              "operator": "lt",
              "value": 24
            }
          ]
        },
        {
          "id": "change-failure-rate-high-performers",
          "title": "Change failure rate is less than 15% since the start of the month",
          "description": "Change Failure Rate (CFR) is the percentage of releases that result in downtime, degraded service, or rollbacks, which can tell you how effective your team is at implementing changes. This metric is also critical for business planning as repeated failure and fix cycles will delay launch of new product initiatives.",
          "conditions": [
            {
              "field": "data.calculationProperties.changeFailureRate.1m.value",
              "operator": "lt",
              "value": 15
            }
          ]
        },
        {
          "id": "failed-deployment-recovery-time-high-performers",
          "title": "Failed deployment recovery time is less than 1 day since the start of the month",
          "description": "FDRT is the amount of time it takes your team to restore service when there’s a service disruption as a result of a failed deployment, like an outage. This metric offers a look into the stability of your software, as well as the agility of your team in the face of a challenge.",
          "conditions": [
            {
              "field": "data.calculationProperties.failedDeploymentRecoveryTime.1m.value",
              "operator": "lt",
              "value": 24
            }
          ]
        }
      ]
    },
    {
      "id": "gold",
      "rules": [
        {
          "id": "deployment-frequency-elite-performers",
          "title": "Deployed at least 30 times to production since the start of the month",
          "description": "Deployment Frequency (DF) is how often you ship changes, how consistent your software delivery is. This enables your organization to better forecast delivery timelines for new features or enhancements to end user favorites.",
          "conditions": [
            {
              "field": "data.calculationProperties.deploymentCountProd.1m.value",
              "operator": "gt",
              "value": 30
            }
          ]
        },
        {
          "id": "lead-time-for-change-elite-performers",
          "title": "Lead time for changes in prod is less than 24 hours since the start of the month",
          "description": "Lead Time for Changes (LTC) is the amount of time between a commit and production. LTC indicates how agile your team is—it not only tells you how long it takes to implement changes, but how responsive your team is to the ever-evolving needs of end users.",
          "conditions": [
            {
              "field": "data.calculationProperties.leadTimeForChangesProd.1m.value",
              "operator": "lt",
              "value": 24
            }
          ]
        },
        {
          "id": "mean-time-to-resolve-elite-performers",
          "title": "Mean time to resolve is less than 1 hours since the start of the month",
          "description": "Average time to resolve incidents that have been closed in the past 24 hours for a specific service, including unresolved incidents since their start.",
          "conditions": [
            {
              "field": "data.calculationProperties.meanTimeToResolve.1m.value",
              "operator": "lt",
              "value": 1
            }
          ]
        },
        {
          "id": "change-failure-rate-elite-performers",
          "title": "Change failure rate is less than 5% since the start of the month",
          "description": "Change Failure Rate (CFR) is the percentage of releases that result in downtime, degraded service, or rollbacks, which can tell you how effective your team is at implementing changes. This metric is also critical for business planning as repeated failure and fix cycles will delay launch of new product initiatives.",
          "conditions": [
            {
              "field": "data.calculationProperties.changeFailureRate.1m.value",
              "operator": "lt",
              "value": 5
            }
          ]
        },
        {
          "id": "failed-deployment-recovery-time-elite-performers",
          "title": "Failed deployment recovery time is less than 1 hour since the start of the month",
          "description": "FDRT is the amount of time it takes your team to restore service when there’s a service disruption as a result of a failed deployment, like an outage. This metric offers a look into the stability of your software, as well as the agility of your team in the face of a challenge.",
          "conditions": [
            {
              "field": "data.calculationProperties.failedDeploymentRecoveryTime.1m.value",
              "operator": "lt",
              "value": 1
            }
          ]
        }
      ]
    }
  ],
  "medianRank": "noRank"
}
```

</details>


# Operational Maturity Example

## Operational Maturity Overview

Operational maturity is about consistently applying best practices to build reliable, efficient software and services. High operational maturity means fewer incidents, faster recovery times, and a reputation for reliability that can set your organization apart. By tracking operational maturity, you can pinpoint where improvements are needed to reduce customer-facing issues, improve response times, and deliver a smoother user experience.

In practice, operational maturity involves an ongoing commitment to high standards across service management, maintenance, and incident response. It’s not just about performance at a specific moment, but about establishing and maintaining processes that ensure quality over the long term. This requires a detailed approach to tracking, measuring, and acting on metrics that reflect the health and stability of your services.

To assess operational maturity, monitor the key performance indicators listed above for each service in your catalog. These metrics provide a structured way to assess both immediate service performance and longer-term reliability. By assigning a tiered ranking based on these measures, you can ensure that your services align with organizational standards and industry benchmarks.

Tracking operational maturity in this way not only gives you a snapshot of current service quality but also builds a foundation for continuous improvement. With clear metrics and thresholds, your team can stay focused on maintaining high standards and addressing issues proactively, reducing the risk of unplanned downtime, and ensuring that your software delivers a high-quality experience at every touchpoint.

## Key Elements to Track for Operational Maturity

**🏅 Gold Tier**&#x20;

* **Error Rate ->** Maintain an error rate below 1% to ensure service stability.
* **P99 Latency ->** Keep P99 latency under 150ms, minimizing delay for most users.
* **Apdex Score ->** Achieve an Apdex score above 0.9 for user satisfaction.
* **Incident Frequency ->** Avoid critical incidents for a full seven days.
* **Security Vulnerabilities ->** Ensure no critical vulnerabilities remain unresolved within the last week.

**🥈 Silver Tier**&#x20;

* **Error Rate ->** Keep error rates below 2.5% to limit service disruptions.
* **P99 Latency ->** Maintain P99 latency below 300ms for reasonable response times.
* **Apdex Score ->** Aim for an Apdex score above 0.8, reflecting user confidence in performance.
* **Incident Frequency ->** Limit critical incidents to one in any given seven-day period.
* **Security Vulnerabilities ->** No more than one critical vulnerability should exist within a seven-day window.

**🥉 Bronze Tier**

* **Error Rate ->** Keep error rates under 5% to avoid major service issues.
* **P99 Latency ->** Ensure P99 latency remains below 500ms for functional performance.
* **Apdex Score ->** Maintain an Apdex score above 0.6, indicating baseline user satisfaction.
* **Incident Frequency ->** Limit to no more than two critical incidents over seven days.
* **Security Vulnerabilities ->** Keep unresolved critical vulnerabilities to two or fewer in a seven-day period.


# Relevant Guides

Coming Soon!


# Troubleshooting

## Reach Out to Customer Support

If you encounter any issues that you're unable to resolve on your own, please don't hesitate to contact our support team at `support@rely.io`.&#x20;

Additionally, if you would like to discuss a specific use-case you're targeting, feel free to [book a session with one of our experts](https://calendar.app.google/fHWH3to58EcSqLdh8) to brainstorm and gain further insights.


# Home Pages


# Overview and Use Cases

The Home Page in [Rely.io](http://rely.io/) streamlines developers' daily activities by centralizing tasks in one place. This reduces the need for context switching and eliminates inefficiencies linked to navigating multiple tools.&#x20;

It offers quick access to Rely's most actionable catalogs, allowing developers to manage their tasks and resources efficiently from a single interface.

{% embed url="<https://youtu.be/QncreT8-V9Y>" %}

## Use Cases

* **Streamlined Daily Activities:** Developers can manage their daily tasks more efficiently by accessing all relevant information and actions from a single interface, reducing the time spent switching between different tools.
* **Quick Access to Actionable Information:** With pre-configured tabs like My Services, My Issues, Open Pull Requests, and Assigned Pull Requests, users can quickly find and manage the most critical aspects of their work.
* **Personalized Dashboard:** Users can customize their Home Page to reflect their unique workflow and preferences, using features like filtering, grouping, and sorting to organize information in a way that best suits their needs.
* **Enhanced Productivity:** By centralizing key activities and providing a tailored experience, the Home Page helps developers focus on their core tasks, improving overall productivity and efficiency.


# Usage Guide


# Creating a New Tab

## From the UI

Coming Soon!

## From the Public API

{% content-ref url="/pages/tYhk0iNq7FYPBgNEX3cO" %}
[Dashboards & Views](/public-api/dashboards-and-views)
{% endcontent-ref %}


# Relevant Guides

Coming Soon!


# Troubleshooting

## Reach Out to Customer Support

If you encounter any issues that you're unable to resolve on your own, please don't hesitate to contact our support team at `support@rely.io`.&#x20;

Additionally, if you would like to discuss a specific use-case you're targeting, feel free to [book a session with one of our experts](https://calendar.app.google/fHWH3to58EcSqLdh8) to brainstorm and gain further insights.


# Self-Service Actions


# Overview and Use Cases

The Developer Self-Service feature in Rely.io empowers developers to build and manage their services and resources independently while maintaining organizational standards. SRE/DevOps teams configure self-service actions following best practices and quality standards, enabling developers to execute these actions with just a button push and approval.&#x20;

This streamlines repetitive tasks, reduces the need for TicketOps, and improves autonomy and efficiency in the development process. Features include a visual builder, audit logs, granular permissions, and the ability to create custom actions.

{% embed url="<https://drive.google.com/file/d/15k_qJ_qxMhoHWQvc0YE9HscCFNMA1fAm/view?usp=sharing>" %}

## Use Cases

* **Accelerated Development**: Developers can quickly provision and manage their resources, reducing wait times and dependencies on other teams, thus speeding up the development lifecycle.
* **Enhanced Autonomy**: By allowing developers to perform self-service actions within predefined guardrails, organizations empower their teams to operate more independently while still adhering to governance and compliance standards.
* **Operational Efficiency**: With self-service capabilities, routine and repetitive tasks are automated, freeing up valuable time for both developers and operations teams to focus on higher-value activities.
* **Audit and Compliance**: Detailed audit logs of self-service actions help organizations maintain compliance and track resource usage, enhancing transparency and accountability.
* **Custom Workflows**: The ability to create custom actions tailored to specific organizational needs helps streamline unique processes and workflows, improving overall efficiency and effectiveness.


# Usage Guide


# Configuring your Self Service Agent

## Overview

The Rely.io Self-Service Agent is a **critical component required to enable self-service action features** within Rely.io. Without it, you won't be able to trigger self-service actions. The Agent is [fully open-source](https://gitlab.com/relyio/backend/self-service-agent).

This agent runs on the customer's side, ensuring that Rely.io does not need write access to the customer's platforms. Once deployed, it will periodically check for pending actions triggered via Rely.io's UI or API and execute them.&#x20;

## Obtaining Your Self-Service Agent API Token

You need to generate an API token to ensure the Rely.io Self-Service Agent can properly interact with Rely.io and listen for events. We have several options for getting the token.

### Get Token from Plugins Page

1. Open the Rely.io platform.
2. Navigate to the **Plugins** page.
3. Open the details of the **Self-Service Agent** plugin.
4. Click **View details** and then **Generate Self Service Token**.

### Get Token from the Self-Service Onboarding Page

1. Open the Rely.io platform.
2. Navigate to the **Self-Service** **Actions** page.
3. Click the **Setup Self-Service Agent** button.
4. On the tab **Generate Rely API token,** click on the **Generate Token**.
5. On the modal dialog, click **Generate token**.
6. Finally, the generated token can be copied from the token input textbox to the clipboard

{% hint style="danger" %}
Generating a new token will invalidate all previously generated tokens.
{% endhint %}

## Installation Method 1: Kubernetes cluster using **Helm (Recommended)**

#### Prerequisites

* A Kubernetes cluster
* [Helm](https://helm.sh/docs/intro/install/) installed on your local machine
* Rely.io Self-Service Agent API Token
* [kubectl](https://kubernetes.io/docs/tasks/tools/) command line app
* [jq](https://jqlang.github.io/jq/download/) command line

#### Step 1: Crete a Kubernetes Namespace

First, create a Kubernetes namespace

```
kubectl create namespace rely-ssa
```

#### **Step 2: Create a Kubernetes Secret with Your API Token**

Create a Kubernetes secret to store your Rely.io API token securely.

<pre class="language-bash"><code class="lang-bash"><strong>kubectl create secret generic relyio-api-token-ssa \
</strong>    --namespace rely-ssa \
    --from-literal=API_TOKEN="YOUR-API-TOKEN"
</code></pre>

Replace `YOUR-API-TOKEN` with your actual API token.

**Step 3: Install the Rely.io Self-Service Agent Chart**

Install the Rely.io Self-Service Agent using the Helm chart.

```bash
helm upgrade --install my-self-service-agent \
    oci://registry-1.docker.io/devrelyio/relyio-self-service-agent-helm \
    --namespace rely-ssa
```

The previous command will install or upgrade the Self Service Agent install to latest version.&#x20;

## **Installation Method 2: Docker**

#### Prerequisites

* [Docker](https://docs.docker.com/engine/install/) installed
* Rely.io Self-Service Agent API Token

**Step 1: Run the Docker Container**

Run the Rely.io Self-Service Agent Docker container with your API token.

```bash
docker run -e API_TOKEN="YOUR-API-TOKEN" devrelyio/self-service-agent:latest
```

Replace `YOUR-API-TOKEN` with your actual API token.

## Managing Secrets and Environment Variables

The Rely.io Self-Service Agent requires tokens to interact with various data sources. The specific tokens to provide will depend on the integrations you want to use in self-service actions. Examples include:

* `GITHUB_TOKEN`: For GitHub integration
* `GITLAB_TOKEN`: For GitLab integration
* `SONARQUBE_TOKEN`: For SonarQube integration
* `PAGERDUTY_TOKEN`: For PagerDuty integration
* `GCP_SERVICE_ACCOUNT`: Google Cloud Service Account credentials

### **Kubernetes (Helm Installation)**

To update the Kubernetes secret with additional environment variables, use the following command:

```bash
kubectl patch secret relyio-api-token-ssa --namespace rely-ssa --patch '{
    "data": {
        "EXAMPLE_ENV_VAR": "'"$(echo -n 'ENV_VAR_VALUE_GOES_HERE' | base64)"'"
    }}'
```

Replace `EXAMPLE_ENV_VAR` and `ENV_VAR_VALUE_GOES_HERE` with your specific variable name and value. &#x20;

For setting up all our previous environment variables at once, we could do it like this:

```bash
kubectl patch secret relyio-api-token-ssa --namespace rely-ssa --patch '{
    "data": {
        "GITHUB_TOKEN": "'"$(echo -n 'YOUR_TOKEN_HERE' | base64)"'",
        "GITLAB_TOKEN": "'"$(echo -n 'YOUR_TOKEN_HERE' | base64)"'",
        "SONARQUBE_TOKEN": "'"$(echo -n 'YOUR_TOKEN_HERE' | base64)"'",
        "PAGERDUTY_TOKEN": "'"$(echo -n 'YOUR_TOKEN_HERE' | base64)"'",
        "GCP_SERVICE_ACCOUNT": "'"$(printf '%s' "$(cat service-account.json | jq -c)" | base64)"'"
    }}'
```

Than re-deploy your agent:

```bash
kubectl rollout restart deployment my-self-service-agent-relyio-self-service-agent-helm \
    --namespace rely-ssa
```

### **Docker**

For the Docker installation, you can pass additional environment variables directly into the `docker run` command. Example:

```bash
docker run -e API_TOKEN="YOUR-API-TOKEN" \
           -e GITHUB_TOKEN="YOUR_TOKEN_HERE" \
           -e GITLAB_TOKEN="YOUR_TOKEN_HERE" \
           -e SONARQUBE_TOKEN="YOUR_TOKEN_HERE" \
           -e PAGERDUTY_TOKEN="YOUR_TOKEN_HERE" \
           -e GCP_SERVICE_ACCOUNT="$(printf '%s' "$(cat service-account.json | jq -c)" \
           devrelyio/self-service-agent:latest
```

## Upgrading the Self-Service Agent

Upgrade to the latest version of the Self-Service Agent; available versions can be checked [here](https://hub.docker.com/r/devrelyio/relyio-self-service-agent-helm/tags)

**Helm**

<pre class="language-bash"><code class="lang-bash"><strong>helm upgrade my-self-service-agent \
</strong><strong>    oci://registry-1.docker.io/devrelyio/relyio-self-service-agent-helm \
</strong><strong>    --namespace rely-ssa
</strong></code></pre>

If a specific version is required, a parameter needs to be added to the previous command just like this:

```bash
helm upgrade relyio-self-service-agent \
    oci://registry-1.docker.io/devrelyio/relyio-self-service-agent-helm \
    --version 0.2.4 \
    --namespace rely-ssa
```

**Docker**

Pull the latest Docker image and run it. Feel free to check and specify for specific versions [here](https://hub.docker.com/r/devrelyio/self-service-agent/tags).&#x20;

```bash
docker pull devrelyio/self-service-agent:latest
docker run -e API_TOKEN="YOUR-API-TOKEN" devrelyio/self-service-agent:latest
```


# Managing your Actions Catalog

## From the UI

Coming Soon!

## From the Public API

{% content-ref url="/pages/JM8vfuBRVvx7kKuWeIlG" %}
[Automations & Self-Service Actions](/public-api/automations-and-self-service-actions)
{% endcontent-ref %}


# Self-Service Actions as Code

As organizations grow and their processes become more mature they will try to standardize on industry best practices and processes. One of the practices implemented by the most established companies is to keep every single configuration as code. It's no different with Self-Service Actions in Rely.io.

Rely.io enables you to leverage industry best-practices such as version control, continuous integration/delivery, and code reviews while creating and maintaining your own Self-Service Actions.&#x20;

{% hint style="info" %}
Currently we only provide automation actions to be included in your CI/CD pipelines for GitLab through CI/CD components. \
\
Support for other providers will be coming shortly.
{% endhint %}

## GitLab CI/CD Components

GitLab CI/CD pipelines are extensible through [CI/CD components](https://docs.gitlab.com/ee/ci/components/). To support you on this task we built some CI/CD components for you to use. You can find them at <https://gitlab.com/detech.ai/ssa-cicd-components>.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FCqBqfepLjbYBGERs9Tu0%2FScreenshot%202024-09-18%20at%2017-20-40%20Rely.io%20_%20ssa-cicd-components%20%C2%B7%20GitLab.png?alt=media&amp;token=0fef9c59-ca92-4165-b8a1-171805a4577f" alt=""><figcaption></figcaption></figure>

## GitLab Example Project

To get you started faster we created an example that will allow you to see how we recommend this integration to be setup. Fork our GitLab example project to get a head start on managing your Self-Service Actions as Code.

You can find the project at <https://gitlab.com/detech.ai/ssa-store-template>.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2Fokewr3vZfo3kDPrEkWRY%2FScreenshot%202024-09-18%20at%2017-20-48%20Rely.io%20_%20ssa-store-template%20%C2%B7%20GitLab.png?alt=media&amp;token=8e4c2b02-bc98-4d62-a353-bf96f8715187" alt=""><figcaption></figcaption></figure>


# Running Actions

## From the UI

Coming Soon!

## From the Public API

{% content-ref url="/pages/5EnltdKjincOYNa5nwom" %}
[Self-Service Action Runs](/public-api/self-service-action-runs)
{% endcontent-ref %}


# Tracking Action Runs

## From the UI

Coming Soon!

## From the Public API

{% content-ref url="/pages/5EnltdKjincOYNa5nwom" %}
[Self-Service Action Runs](/public-api/self-service-action-runs)
{% endcontent-ref %}


# Relevant Guides

Coming Soon!


# Troubleshooting

## Reach Out to Customer Support

If you encounter any issues that you're unable to resolve on your own, please don't hesitate to contact our support team at `support@rely.io`.&#x20;

Additionally, if you would like to discuss a specific use-case you're targeting, feel free to [book a session with one of our experts](https://calendar.app.google/fHWH3to58EcSqLdh8) to brainstorm and gain further insights.


# Plugins & Automation


# What happens when you install a Plugin?

## **Integration with Your Engineering Stack**

Rely.io seamlessly integrates with your engineering stack through plugins, each enhancing the platform with specific functionalities. Begin your Rely.io journey by using these plugins to populate your software catalog with services, cloud resources, and more.

For instructions on how to setup your first plugin check our [getting started](/getting-started-guide) guide for a basic starting point, however if you want to know further check [self-hosting a plugin](/plugins-and-automation/self-hosting-plugins-using-galaxy) and the [plugins installations guides](/plugins-and-automation/plugin-installation-guides).&#x20;

If you are curious about what happens *under-the-hood* when installing a plugin continue readin&#x67;*.*

## **Behind-the-Scenes**

* **Data Model Expansion:** Installing a plugin triggers an expansion of your [data model](/basic-concepts/data-model) within [Rely.io](http://Rely.io). This expanded model can accurately represent and display entities related to the plugin's data source.
* **Mass Discovery Run:** Post-setup, Rely.io initiates a mass discovery run to query the data source, ingesting entities based on the assets you selected. This ensures your Rely.io catalog mirrors the external data source accurately.
* **Synchronization:** Rely uses webhooks for real-time updates from your data sources, ensuring your catalog is up-to-date. For plugins without webhook support, Rely.io schedules periodic discovery runs to keep your catalog synchronized.
* **Automation Rules:** Once a plugin is installed, [Rely.io](https://rely.io) automatically creates automation rules to link, map, and auto-populate your key assets (like services and resources) based on the data provided by the plugin’s data source.&#x20;
  * For example, installing a Git provider plugin means repositories identified during the discovery phase will automatically create service entities in your catalog.&#x20;
  * These entities will be enriched with vital information such as the code languages, repository links, README content, etc.&#x20;
  * As more plugins are installed and more automation rules created, your catalog becomes more  detailed enhancing your understanding and management of your tech ecosystem.


# Self-Hosting Plugins using Galaxy

Galaxy is an open source solution developed by Rely.io that enables seamless integration of third-party systems with our internal developer portal. With Galaxy, you can leverage existing [integrations](https://www.rely.io/product/integrations) to ingest your data into Rely.io or create custom integrations tailored to your needs. As an open source project, its repository can be found [here](https://github.com/Rely-io/galaxy-oss).

Built with Python, Galaxy offers reusable components, making it easy to add integrations to the framework. It employs JQ syntax to accurately map data from third-party APIs into the Rely data model.

### Installation

#### Pre-requisites

To setup an integration with a third-party tool you must create a plugin for it. If you haven't done it yet, please follow the instructions on the next step "*Creating the plugin*". Otherwise feel free to skip this step.

**Creating the plugin**

In your Rely.io application, go to `Portal Builder` > `Plugins` and select "*Add Data Source*".&#x20;

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2F4KIky6iFYH0AtxULvZyQ%2Fimage.png?alt=media&amp;token=93978a37-7fc8-4f8a-89c1-a8412e6ffa8a" alt=""><figcaption></figcaption></figure>

Select the tool you'll be using and tick the "*Is your plugin self hosted?*" option. Fill the required information (if any required) and submit.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FFbAqtiU0stpGoGTsZGOF%2Fimage.png?alt=media&amp;token=4d07c6f5-531c-43f7-9c03-b3773ee9e074" alt=""><figcaption></figcaption></figure>

Select *"View details"* on the plugin you want to setup and move to the *"self-hosted instructions"* tab.&#x20;

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FWf2X6GNmsf15wDnwt4gV%2Fimage.png?alt=media&amp;token=086aded2-b9a2-4bdd-93cd-3635fa55ed52" alt=""><figcaption></figcaption></figure>

You'll notice there's a command to deploy Galaxy into a Kubernetes cluster using an Helm chart.  You might need to adjust the command to include additional variables required by the plugin, The info on the variables required to setup for the plugin should be checked on its own [documentation](/plugins-and-automation/plugin-installation-guides).

{% hint style="info" %}
For more detailed information regarding Galaxy installation and configuration options check the [open source repository](https://github.com/Rely-io/galaxy-oss).
{% endhint %}


# Automation Rules


# Overview and Use Cases

Automation Rules in Rely.io enhance the efficiency and consistency of the software catalog by standardizing and automating processes across different tools. These rules help in unifying entity representations from various data sources and ensuring cross-tool uniformity.&#x20;

Automation Rules can be configured to automatically link, map, and populate key assets, making the catalog richer and more accurate as more plugins are installed.

{% embed url="<https://youtu.be/TVvWpG-Zd4M>" %}

## Use Cases

* **Unified Entity Representation:** Different perspectives from various tools are aggregated into cohesive entities, simplifying management and ensuring consistency.
* **Cross-Tool Standardization:** Automation rules help standardize entities like pull requests, issues, and services across different platforms, maintaining uniformity and clarity.
* **Enhanced Data Integration:** As plugins are installed, automation rules enrich the catalog with detailed and accurate information from multiple sources, improving the overall data quality and usability.


# Usage Guide


# Creating an Automation Rule

## From the UI

Coming Soon!

## From the Public API

{% content-ref url="/pages/JM8vfuBRVvx7kKuWeIlG" %}
[Automations & Self-Service Actions](/public-api/automations-and-self-service-actions)
{% endcontent-ref %}


# Updating an Automation Rule

## From the UI

Coming Soon!

## From the Public API

{% content-ref url="/pages/JM8vfuBRVvx7kKuWeIlG" %}
[Automations & Self-Service Actions](/public-api/automations-and-self-service-actions)
{% endcontent-ref %}


# Tracking Automation Changes

## From the UI

Coming Soon!

## From the Public API

{% content-ref url="/pages/2M1M6xS8JAqJ1ts2oq3F" %}
[Audit Logs](/public-api/audit-logs)
{% endcontent-ref %}


# Managing Automation Suggestion

## From the UI

{% embed url="<https://drive.google.com/file/d/1ziKr2sz063v9y5n28PRPWXHk-OhHDL77/view?usp=drive_link>" %}

## From the Public API

{% content-ref url="/pages/FwRG9gsLV4UbYZw0zVkv" %}
[Automation Suggestions](/public-api/automation-suggestions)
{% endcontent-ref %}


# Relevant Guides

<table data-view="cards"><thead><tr><th>Relevant Guides</th></tr></thead><tbody><tr><td><a href="/guides-and-tutorials/populating-your-service-catalog-with-github-and-datadog">Populating your Service Catalog with Github and Datadog</a></td></tr></tbody></table>


# Troubleshooting

## Reach Out to Customer Support

If you encounter any issues that you're unable to resolve on your own, please don't hesitate to contact our support team at `support@rely.io`.&#x20;

Additionally, if you would like to discuss a specific use-case you're targeting, feel free to [book a session with one of our experts](https://calendar.app.google/fHWH3to58EcSqLdh8) to brainstorm and gain further insights.


# Plugin Installation Guides


# Argo CD

{% hint style="info" %}
This plugin is part of Pro and Enterprise plan only
{% endhint %}

### **Introduction**

This document provides step-by-step instructions for integrating your IDP software with ArgoCD. The integration can be achieved through two methods:

1. **Synchronous Method**: Fetching data using a service account token.
2. **Asynchronous Method**: Receiving data via webhooks.

**Ideally for best performance and up to the date information you should have both methods enabled.**

Before proceeding, ensure you have the following information:

* Plugin Name: A unique identifier for your application.
* BaseURL: The public URL of your ArgoCD server.
* Account Token: A token with read permissions for ArgoCD.
* Webhook Token: A token for receiving live changes via webhooks.

### **Method 1: Synchronous Data Fetching**

#### **Creating a Service Account in ArgoCD**

To fetch data synchronously, you need to create a service account in ArgoCD with read permissions.

#### Steps:

1. **Create a Service Account**:
   * Refer to [Creating an Argo CD Service Account](https://www.arthurkoziel.com/creating-argo-cd-service-account/) for detailed steps.
   * Additionally, consult the official ArgoCD documentation on [Service Account Token Generation](https://argo-cd.readthedocs.io/en/stable/user-guide/commands/argocd_account_generate-token/).
2. **Set the Token in IDP Software**:
   * After creating the service account and generating the token, enter this token in plugin configuration as the 'Account Token'.

### **Method 2: Asynchronous Data Fetching via Webhooks**

#### **Setting Up Notifications Service in ArgoCD**

For asynchronous data fetching, configure the notifications service in ArgoCD.

#### Requirements:

* ArgoCD version 2.10 or later: Use the built-in notifications controller.
* Earlier versions of ArgoCD: Install the argocd-notifications helm chart.

#### Installation:

* For ArgoCD 2.10 or later, refer to the [Notifications Controller Documentation](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/).
* For earlier versions, use the Helm chart available at [ArgoCD Notifications Documentation](https://argocd-notifications.readthedocs.io/en/stable/), with the chart details:

  ```java
  chart      = "argocd-notifications"
  repository = "https://argoproj.github.io/argo-helm"
  version    = "1.8.1"
  ```
* Configure `values.yaml`

  ```java
  secret:
    create: true
    annotations: {}
    name: ""
    items:
      webhooks-token: <WEBHOOK_API_TOKEN_ON_https://web-env-dev.rely.io/settings>

  notifiers:
    service.webhook.sync-running:
      url: https://magneto.rely.io/api/v1/webhooks/argocd
      headers:
        - name: Content-Type
          value: application/json
        - name: Authorization
          value: Bearer $webhooks-token

  subscriptions:
    # subscription for on-sync-status-unknown trigger notifications
    - recipients:
      - sync-running
      triggers:
        - on-sync-running
        - on-sync-succeeded
        - on-sync-failed
        - on-sync-status-unknown
        - on-deployed
        - on-health-degraded
        - on-created
        - on-deleted

  templates:
    template.app-deleted: |
      webhook:
        sync-running:
          method: POST
          body: |
            {
              "type": "deleted",
              "metadata": {
                "name": "{{.app.metadata.name}}",
                "namespace": "{{.app.spec.destination.namespace}}",
                "annotations": {{ toJson .app.metadata.annotations }},
                "labels": {{ toJson .app.metadata.labels }},
                "creationTimestamp": "{{.app.metadata.creationTimestamp}}"
              }
            }
    template.app-sync-running: |
      webhook:
        sync-running:
          method: POST
          body: |
  					 {
              "type": "generic",
              "metadata": {
                "name": "{{.app.metadata.name}}",
                "namespace": "{{.app.spec.destination.namespace}}",
                "annotations": {{ toJson .app.metadata.annotations }},
                "labels": {{ toJson .app.metadata.labels }},
                "creationTimestamp": "{{.app.metadata.creationTimestamp}}",
                "ownerReferences": {{ toJson .app.metadata.ownerReferences }}
              },
              "spec": {
                "project": "{{.app.spec.project}}",
                "source": {
                  "repoURL": "{{.app.spec.source.repoURL}}",
                  "path": "{{.app.spec.source.path}}",
                  "targetRevision": "{{.app.spec.source.targetRevision}}"
                },
                "destination": {
                  "server": "{{.app.spec.destination.server}}",
                  "namespace": "{{.app.spec.destination.namespace}}"
                },
                "syncPolicy": {{ toJson .app.spec.syncPolicy }}
              },
              "status": {
                "conditions": {{ toJson .app.status.conditions | default "[]" }},
                "health": {
                  "status": "{{.app.status.health.status}}",
                  "message": "{{.app.status.health.message}}"
                },
                "operationState": {
                  "finishedAt": "{{.app.status.operationState.finishedAt}}",
                  "startedAt": "{{.app.status.operationState.startedAt}}",
                  "message": "{{.app.status.operationState.message}}",
                  "phase": "{{.app.status.operationState.phase}}",
                  "syncResult": {
                    "revision": "{{.app.status.operationState.operation.sync.revision}}"
                  }
                },
                "sync": {
                  "status": "{{.app.status.sync.status}}"
                }
              }
            }

  triggers:
    trigger.on-created: |
      - description: Application is created.
        send:
        - app-sync-running
        when: true
    trigger.on-deleted: |
      - description: Application is deleted.
        send:
        - app-deleted
        when: app.metadata.deletionTimestamp != nil
    trigger.on-deployed: |
      - description: Application is synced and healthy. Triggered once per commit.
        send:
        - app-sync-running
        when: app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy'
    trigger.on-health-degraded: |
      - description: Application has degraded
        send:
        - app-sync-running
        when: app.status.health.status == 'Degraded'
    trigger.on-sync-failed: |
      - description: Application syncing has failed
        send:
        - app-sync-running
        when: app.status.operationState.phase in ['Error', 'Failed']
    trigger.on-sync-running: |
      - description: Application syncing has succeeded
        send:
        - app-sync-running
        when: app.status.operationState.phase in ['Running']
    trigger.on-sync-status-unknown: |
      - description: Application status is 'Unknown'
        send:
        - app-sync-running
        when: app.status.sync.status == 'Unknown'
    trigger.on-sync-succeeded: |
      - description: Application syncing has succeeded
        send:
        - app-sync-running
        when: app.status.operationState.phase in ['Succeeded']
    defaultTriggers: |
      - on-sync-status-unknown
  ```


# AWS

{% hint style="info" %}
This plugin is part of Pro and Enterprise plan only
{% endhint %}

## Overview

AWS is a comprehensive and widely adopted cloud platform, offering an extensive range of services and solutions to power your applications and infrastructure. With Rely.io's integration, you can maximize the benefits of AWS's offerings by tapping into a broad array of information around various AWS services.

## Installation Guide

To successfully set up the integration with AWS, follow the steps detailed below:

#### 1. Start Creating an AWS User

Log into your AWS Management Console and navigate to `IAM` > `Users`.

1. Click `Add users`.
2. Enter a name for your user (e.g. "Rely")
3. Click `Next`

Note: You can leave the "Provide user access to the AWS Managment Console" option un-checked as Rely only requires programmatic access.

Step 2 of this form is meant for you to specify the new user's policies.

#### 2. Create an access Policy with the appropriate permissions

1. In the `Permission options` section click the `Attach Policies Directly` tab
2. Click the `Create Policy` button

This will open up a new tab on your browse in policy creation wizard.

1. Click the `JSON` button that will open up a configuration input box and paste the following payload.

<details>

<summary>AWS Policy Config</summary>

```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "ec2:Describe*",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": "elasticloadbalancing:Describe*",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "cloudwatch:ListMetrics",
                "cloudwatch:GetMetricStatistics",
                "cloudwatch:Describe*"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": "autoscaling:Describe*",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "rds:Describe*",
                "rds:ListTagsForResource",
                "ec2:DescribeAccountAttributes",
                "ec2:DescribeAvailabilityZones",
                "ec2:DescribeInternetGateways",
                "ec2:DescribeSecurityGroups",
                "ec2:DescribeSubnets",
                "ec2:DescribeVpcAttribute",
                "ec2:DescribeVpcs"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "cloudwatch:GetMetricStatistics",
                "cloudwatch:ListMetrics",
                "cloudwatch:GetMetricData",
                "logs:DescribeLogStreams",
                "logs:GetLogEvents",
                "devops-guru:GetResourceCollection"
            ],
            "Resource": "*"
        },
        {
            "Action": [
                "devops-guru:SearchInsights",
                "devops-guru:ListAnomaliesForInsight"
            ],
            "Effect": "Allow",
            "Resource": "*",
            "Condition": {
                "ForAllValues:StringEquals": {
                    "devops-guru:ServiceNames": [
                        "RDS"
                    ]
                },
                "Null": {
                    "devops-guru:ServiceNames": "false"
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:Get*",
                "s3:List*",
                "s3:Describe*",
                "s3-object-lambda:Get*",
                "s3-object-lambda:List*"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "cloudformation:Describe*",
                "cloudformation:EstimateTemplateCost",
                "cloudformation:Get*",
                "cloudformation:List*",
                "cloudformation:ValidateTemplate",
                "cloudformation:Detect*"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "cloudformation:DescribeStacks",
                "cloudformation:ListStacks",
                "cloudformation:ListStackResources",
                "cloudwatch:GetMetricData",
                "cloudwatch:ListMetrics",
                "ec2:DescribeSecurityGroups",
                "ec2:DescribeSubnets",
                "ec2:DescribeVpcs",
                "kms:ListAliases",
                "iam:GetPolicy",
                "iam:GetPolicyVersion",
                "iam:GetRole",
                "iam:GetRolePolicy",
                "iam:ListAttachedRolePolicies",
                "iam:ListRolePolicies",
                "iam:ListRoles",
                "logs:DescribeLogGroups",
                "lambda:Get*",
                "lambda:List*",
                "states:DescribeStateMachine",
                "states:ListStateMachines",
                "tag:GetResources",
                "xray:GetTraceSummaries",
                "xray:BatchGetTraces"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "logs:DescribeLogStreams",
                "logs:GetLogEvents",
                "logs:FilterLogEvents",
                "logs:StartQuery",
                "logs:StopQuery",
                "logs:DescribeQueries",
                "logs:GetLogGroupFields",
                "logs:GetLogRecord",
                "logs:GetQueryResults"
            ],
            "Resource": "arn:aws:logs:*:*:log-group:/aws/lambda/*"
        },
        {
            "Sid": "AWSOrganizationsReadOnly",
            "Effect": "Allow",
            "Action": [
                "organizations:Describe*",
                "organizations:List*"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AWSOrganizationsReadOnlyAccount",
            "Effect": "Allow",
            "Action": [
                "account:GetAlternateContact",
                "account:GetContactInformation",
                "account:ListRegions"
            ],
            "Resource": "*"
        },
        {
            "Sid": "CloudWatchReadOnlyAccessPermissions",
            "Effect": "Allow",
            "Action": [
                "application-autoscaling:DescribeScalingPolicies",
                "autoscaling:Describe*",
                "cloudwatch:BatchGet*",
                "cloudwatch:Describe*",
                "cloudwatch:GenerateQuery",
                "cloudwatch:Get*",
                "cloudwatch:List*",
                "logs:Get*",
                "logs:List*",
                "logs:StartQuery",
                "logs:StopQuery",
                "logs:Describe*",
                "logs:TestMetricFilter",
                "logs:FilterLogEvents",
                "logs:StartLiveTail",
                "logs:StopLiveTail",
                "oam:ListSinks",
                "sns:Get*",
                "sns:List*",
                "rum:BatchGet*",
                "rum:Get*",
                "rum:List*",
                "synthetics:Describe*",
                "synthetics:Get*",
                "synthetics:List*",
                "xray:BatchGet*",
                "xray:Get*"
            ],
            "Resource": "*"
        },
        {
            "Sid": "OAMReadPermissions",
            "Effect": "Allow",
            "Action": [
                "oam:ListAttachedLinks"
            ],
            "Resource": "arn:aws:oam:*:*:sink/*"
        },
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "eks:ListEksAnywhereSubscriptions",
                "eks:DescribeFargateProfile",
                "eks:ListTagsForResource",
                "eks:DescribeInsight",
                "eks:ListAccessEntries",
                "eks:ListAddons",
                "eks:DescribeEksAnywhereSubscription",
                "eks:DescribeAddon",
                "eks:ListAssociatedAccessPolicies",
                "eks:DescribeNodegroup",
                "eks:ListUpdates",
                "eks:DescribeAddonVersions",
                "eks:ListIdentityProviderConfigs",
                "eks:ListNodegroups",
                "eks:DescribeAddonConfiguration",
                "eks:DescribeAccessEntry",
                "eks:DescribePodIdentityAssociation",
                "eks:ListInsights",
                "eks:ListPodIdentityAssociations",
                "eks:ListFargateProfiles",
                "eks:DescribeIdentityProviderConfig",
                "eks:DescribeUpdate",
                "eks:AccessKubernetesApi",
                "eks:DescribeCluster",
                "eks:ListClusters",
                "eks:ListAccessPolicies"
            ],
            "Resource": "*"
        }
    ]
}
```

</details>

2. Click `Next`
3. Assign a descriptive name to your Policy (e.g. "RelyPermissionsPolicy")
4. You should see a pop-up indicating you that your policy has just been created

#### 3. Create a User associated with the Access Policy that was just created

1. Go back to your the tab you were on before clicking `Create Policy` .
2. Hit the refresh button besides the `Create Policy` this will refresh the list of available policies to select from.
3. Search for the policy name you picked earlier.
4. Select the policy that you have just created and click `Next`
5. Review the user's configuration and click `Create User`
6. You should see a pop-up indicating you that your user has just been created, in it there's a button labeled `View User`, click it!

#### 4. Collect the Required AWS information

1. Inside the User's page, hit `Create access key`
2. Select `Third-party provider`
3. At this point AWS will tell you about the possibility of creating temporary security credentials instead of long term ones. This would require you to re-make the Rely plugin configuration cyclically. At this point you can just confirm your choice and click `Next`
4. You can just ignore the long tag value and hit `Create access Key`
5. Keep this tab open for the following step, as you'll need to copy past the `Access Key` and `Secret Access Key` soon enough
6. You will also need to know your organization's `Account ID` which can be seen by opening up the user menu situated in the top-right corner of your AWS console.

#### 5. Connect to the Rely Platform

You can now return to the Rely.io platform and start the integration process with AWS CloudWatch. Open the Rely platform and start by navigating to the data-sources page. Click the "Add Data Source" button and select "AWS".

This will prompt a modal to appear asking you for the information necessary to successfully integrate the AWS CloudWatch your account.

Start by giving an expressive name to your data source instance by filling in the “Collector Name” field. This is an unique name that will allow you to distinguish between multiple data source instances.

Fill in all of the values according to the information you obtained in step 4 of this guide. Click *Create* to finish the integration process.

After you submit your form, an entity discovery run will be kickstarted that can take a few minutes. By the end of this discovery run:

* New blueprints will be added to your data model
* Entities will be queries from the data-source and added to your software catalog
* These entities will be periodically updated to ensure they remain in sync with their external counter-parts


# Azure

{% hint style="info" %}
This plugin is part of Pro and Enterprise plan only
{% endhint %}

## Overview

Integrating Azure with Rely.io enhances your ability to monitor and manage Azure resources through a centralized platform. By connecting Azure to Rely.io, you can automate the collection of telemetry data from your Azure environment, enabling efficient resource management, security compliance, and operational health insights.

## Installation Guide

To set up the Azure integration with Rely.io, you have the option to follow the steps using the Azure Portal UI or the Azure Command Line Interface (CLI). These steps assume you have the necessary permissions to create and manage service accounts and subscriptions within your Azure environment.

### Option 1: **Using Azure CLI**

### Option 2

**1. Create an Azure Service Principal**

A Service Principal in Azure is a security identity used by applications, services, and automation tools to access specific Azure resources. Follow these steps to create a Service Principal:

* **Log in to Azure Portal**: Access your Azure account by logging into the Azure Portal.
* **Navigate to Azure Active Directory**: Go to the Azure Active Directory (AAD) service from the navigation pane.
* **App Registrations**: Select "App Registrations" and click on the "New registration" button.
* **Register an Application**: Enter the name for your application/service (e.g. "Rely Integration App").
  * Leave the "Supported account types" to the default setting and the "Redirect URI" section empty.
  * Click "Register".
* **Capture Application (Client) ID and Directory (Tenant) ID**: Once registered, note down the "Application (Client) ID" and "Directory (Tenant) ID "from the application overview page.
* **Create a Client Secret**: Under the same application, navigate to "Certificates & secrets" and click on "New client secret".
  * Provide the secret with a name (e.g. "Rely.io Integration Password"), set an expiration period, and then save it.
  * Ensure to copy the secret value as it won't be displayed again.

**2. Grant Azure Service Principal Access to Your Subscription**

* **Navigate to Subscriptions**: In the Azure Portal, go to "Subscriptions" and select the subscription you intend to monitor.
* **Capture Subscription ID:** Take note of the Application (Client) ID from the subscription overview page.
* **Access Control (IAM)**: Go to the "Access control (IAM)" section and click on "Add role assignment".
* **Assign a Role**: Choose the "Reader" role and continue to the next step .
  * Search for the Service Principal you created and assign it the role (e.g. "Rely Integration App")

### **Connect to the Rely Platform**

With the Service Principal set up and granted access to your Azure subscription, you can now connect your Azure account with Rely.

* **Open the Rely Platform**: Navigate to the data-sources page within the Rely.io platform.
* **Add Data Source**: Click on the "Add Data Source" button and select "Azure".
* **Configuration Modal**: A modal will appear requesting information necessary for integrating Azure with your Rely.io account.

Fill in the required fields:

* **Collector Name**: Enter a descriptive name for your Azure collector.
* **App ID**: Paste the Application (Client) ID of the Service Principal.
* **Tenant ID**: Paste the Directory (Tenant) ID associated with the Service Principal.
* **Password**: Enter the Client Secret created for the Service Principal.
* **Subscription ID**: Enter the ID of the Azure subscription you want to monitor.

Click "Create" to finalize the integration process.

After submitting the form, Rely.io will begin an entity discovery run, which may take a few minutes. Upon completion:

* New blueprints will be incorporated into your data model.
* Entities will be fetched from the data source and added to your software catalog.
* These entities will be periodically updated to ensure they remain aligned with their Azure counterparts.

## Congratulations!

You have successfully set up the Azure integration for Rely.io's platform. This integration empowers you with comprehensive insights and management capabilities for your Azure resources, streamlining operations and enhancing security compliance within your cloud environment.


# Backstage

{% hint style="info" %}
This plugin is part of Pro and Enterprise plan only
{% endhint %}

## Rely Migration Plugin for Backstage

Welcome to the `rely-migration-plugin` for Backstage by Rely.io. This plugin seamlessly integrates with Backstage to export essential data to the Rely.io Identity Data Provider (IDP). It offers two modes of operation: a one-time data export via a dedicated endpoint, and an automated, scheduled data export using a cron job.

Feel free to reference the NPM package page for more detailed information.

### Features

* **One-time Export**: Easily migrate your data to Rely.io with a single API call.
* **Scheduled Export**: Set up a cron job to regularly export data, ensuring continuous synchronization with Rely.io.

### Installation

To get started with the Rely Migration Plugin, follow these installation steps:

1. **Install the Plugin**:

   ```
   cd packages/backend && yarn add @rely/backstage-plugin-rely-migration-plugin-backend
   ```
2. **Create the Plugin File**: In your Backstage backend, create a new file at `packages/backend/src/plugins/rely.ts` with the following content:

   ```
   import { PluginEnvironment } from '../types';
   import { createRouter } from '@rely/backstage-plugin-rely-migration-plugin-backend';
   import { parseConfigs } from '@rely/backstage-plugin-rely-migration-plugin-backend';

   export default async function createPlugin(env: PluginEnvironment) {
     const routerOptions = await parseConfigs(env);
     return await createRouter(routerOptions);
   }
   ```
3. **Update the Backend Index**: Modify `packages/backend/src/index.ts` to include the Rely plugin:

   ```
   import rely from './plugins/rely';
   ...
   const relyEnv = useHotMemoize(module, () => createEnv('rely'));
   ...
   apiRouter.use('/rely', await rely(relyEnv));
   ```
4. **Configure Proxy and Rely in `app-config.yaml`**: Add the following configuration to your `app-config.yaml`:

   ```
   proxy:
     '/rely':
       target: https://magneto.rely.io
       headers:
         Authorization: Bearer <WEBHOOK_API_TOKEN_ON https://webapp.rely.io/settings>

   rely:
     # Enable/disable gzip
     cron:
       enabled: true
       schedule: '0 * * * *'
     # Define entity filters for data export
     entityFilters: []
       # Example filters:
       # - kind: ['API', 'Component']
       # - metadata.name: 'a'
       #   metadata.namespace: 'b'
   ```

### How to Use

* **One-time Export**: Trigger the endpoint `<backstage-hostname>/api/rely/migrate` to start a one-time export.
* **Scheduled Export**: If the cron job is enabled in the configuration, the plugin will automatically export data at specified intervals.

### Configuration Details

* `cron.enabled`: Enable or disable the cron job for scheduled exports.
* `cron.schedule`: Define the cron schedule for automated data exports.
* `entityFilters`: Specify filters for the entities to be exported. For more details on structuring these filters, refer to the [Backstage EntityFilterQuery documentation](https://backstage.io/docs/reference/catalog-client.entityfilterquery/).

### Development and Local Testing

* **Running in the Backstage App**: Start the Backstage app (`yarn start` at the root) and navigate to `/rely-migration-plugin`.
* **Isolated Plugin Development**: Run `yarn start` in the plugin directory for faster iteration, startup, and hot reloads. This setup is intended for local development only.

***

Thank you for choosing Rely.io for your identity management solutions. We are committed to providing seamless integration and top-notch support for Backstage users. For any issues or contributions, please feel free to open an issue or pull request in our repository.


# Bitbucket

## Overview

Bitbucket is a platform for hosting and versioning code, facilitating collaboration among developers. Leverage the power of Bitbucket's vast repository data within Rely.io for a comprehensive view of your software lifecycle.

## Installation Guide

### Required permissions

During the configuration process, you'll be asked to authorize the [Rely.io](http://rely.io/) App to have specific permissions in your account for the plugin to function properly:\
\
**Read**

<table data-header-hidden><thead><tr><th></th><th width="285"></th><th></th></tr></thead><tbody><tr><td>✅ Account</td><td>✅ Issues</td><td>✅ Build Pipelines</td></tr><tr><td>✅ Project</td><td>✅ Repositories</td><td>✅ Pull Requests</td></tr><tr><td>✅ Team Membership</td><td></td><td></td></tr></tbody></table>

{% hint style="info" %}
The necessary permission scopes will be automatically filled in for you so you don't have to worry about that.&#x20;
{% endhint %}

### Steps to Integrate Bitbucket with Rely.io

1. Open the Rely.io platform and start by navigating to the `Plugins` page in the `Portal Builder`.
2. Click the `Add Data Source` button and select `Bitbucket`.
3. You'll be redirected to Bitbucket's app integration form, login to your account.
4. Submit the form by providing the necessary permissions
5. You'll be redirected back to Rely.io
6. Provide an expressive name to this integration that allows you to easily identify the source
7. Click `Submit` to finalize the integration.

{% hint style="info" %}
To prevent pulling outdated or stale data from your tools and flooding your catalog with unactionable entities, our plugins are set by default with policies to reduce noise.

For instance in the case of Git providers:

* Repositories with no activity over the last 3 months are ignored
* Repositories that have been archived are also ignored
* All entities related to ignored repositories (Pull Requests, Issues, Deployments, etc.) are consequently ignored
  {% endhint %}

After you add the Bitbucket plugin, an entity discovery run will be triggered. The initial discovery run can take up to a few minutes. By the end of this discovery run:

* New blueprints will be added to your data model
* Entities retrieved from the data source will be added to the [Discovery](https://webapp.rely.io/data-model/discovery) page for you to either approve or reject them

{% hint style="info" %}
The plugin periodically updates all retrieved entities to ensure they stay in sync with their external counterparts.
{% endhint %}

Once the initial discovery run completes successfully you should see your GitLab plugin under the `Active` section of the `data sources` page.


# Confluence

*Coming Soon!*


# Datadog

{% hint style="info" %}
This plugin is part of Pro and Enterprise plan only
{% endhint %}

## Overview

Datadog is a powerful monitoring and analytics platform that provides comprehensive insights into your application's performance and infrastructure. By integrating Datadog with Rely.io's platform, you can leverage the telemetry data collected you host within Datadog in Rely's platform.

## Installation Guide

To get started with the Datadog integration, follow the steps below.

#### 1. Generate Keys

Before you can connect Rely.io to Datadog, you need to generate the required API and Application Keys. The following guide was based on the [official documentation](https://docs.datadoghq.com/account_management/api-app-keys/) provided by Datadog.

**API Keys**

1. Log in to your Datadog account.
2. Navigate to the API Keys section in your account settings.
3. Click on the "New Key" button.
4. Enter a name for your API key.
5. Click "Create API key" to generate the key.

**Application Keys**

Application keys, in conjunction with your organization's API key, provide access to Datadog's programmatic API. They are associated with the user account that created them and have the permissions and scopes of the user by default. To generate an application key, please follow these steps:

1. Log in to your Datadog account.
2. Go to the Application Keys section in your account settings.
3. Click on the "New Key" button.
4. Enter a name for your application key.
5. Leave the key scopes empty
6. Click "Create Application key" to generate the key.

#### 2. Determine Datadog Site

Datadog offers different sites throughout the world, each one being completely independent. To successfully enable Rely.io to retrieve information from Datadog, it's crucial to determine the site where your data is housed.

You can identify which site you are on by matching your Datadog website URL to the site URL in the table below. For more information, reference the [official documentation](https://docs.datadoghq.com/getting_started/site/) provided by Datadog.

<table><thead><tr><th>SITE</th><th width="148">SITE URL</th><th>SITE PARAMETER</th><th>LOCATION</th></tr></thead><tbody><tr><td>US1</td><td><code>https://app.datadoghq.com</code></td><td><code>datadoghq.com</code></td><td>US</td></tr><tr><td>US3</td><td><code>https://us3.datadoghq.com</code></td><td><code>us3.datadoghq.com</code></td><td>US</td></tr><tr><td>US5</td><td><code>https://us5.datadoghq.com</code></td><td><code>us5.datadoghq.com</code></td><td>US</td></tr><tr><td>EU1</td><td><code>https://app.datadoghq.eu</code></td><td><code>datadoghq.eu</code></td><td>EU</td></tr><tr><td>US1-FED</td><td><code>https://app.ddog-gov.com</code></td><td><code>ddog-gov.com</code></td><td>US</td></tr><tr><td>AP1</td><td><code>https://ap1.datadoghq.com</code></td><td><code>ap1.datadoghq.com</code></td><td>Japan</td></tr></tbody></table>

#### 3. Connect to the Rely Platform

Now that you have generated the necessary keys, you can proceed to connect your Datadog account with Rely.

Open the Rely platform and start by navigating to the data-sources page. Click the "Add Data Source" button and select "Datadog".

This will prompt a modal to appear asking you for the information necessary to successfully integrate Datadog with your Rely.io account.

Fill in the required input fields:

* **Collector Name**: Enter a name for the collector.
* **API Key**: Paste the API key generated in the previous step.
* **App Key**: Paste the application key generated in the previous step.
* **Site**: Specify the Datadog site where your data is hosted.

Click *Create* to finish the integration process.

After you submit your form, an entity discovery run will be kickstarted that can take a few minutes. By the end of this discovery run:

* New blueprints will be added to your data model
* Entities will be queries from the data-source and added to your software catalog
* These entities will be periodically updated to ensure they remain in sync with their external counter-parts

Congratulations! You have successfully set up the Datadog integration for Rely.io's platform.


# Dynatrace

*Coming Soon!*


# Flux

{% hint style="info" %}
This plugin is part of Pro and Enterprise plan only
{% endhint %}

{% hint style="warning" %}
This plugin is only available through self-hosting Galaxy
{% endhint %}

## Overview

Flux is a tool that enables continuous and automated deployment of workloads to Kubernetes. It ensures that the desired state of your Kubernetes cluster as represented in version control is consistently deployed and kept up-to-date.

Integrating your Flux installation with Rely.io enables tracking of mission-critical Flux resources and monitored repositories and applications, as well as the status of deployments when Flux triggers reconciliations.

## Installation Guide

This plugin requires access to the Kubernetes cluster in which Flux is deployed. Because of this, it is only available through our self-hosted Galaxy offering. See [Self-Hosting Plugins using Galaxy](/plugins-and-automation/self-hosting-plugins-using-galaxy) on how to get started.

The plugin will discover all Flux resources in your cluster but will only track reconciliations for namespaces configured during installation.

The plugin leverages Flux's [Notification Controller](https://fluxcd.io/flux/components/notification/) to monitor events related to your Flux-tracked Kubernetes resources. This requires the plugin to create [Alerts](https://fluxcd.io/flux/components/notification/alerts/) and [Providers](https://fluxcd.io/flux/components/notification/providers/) in the namespaces you wish to monitor. Make sure the account installing the Helm Chart has the required permissions to do so.

### Setup

To configure the Flux integration within your Rely.io instance, follow these steps:

1. Navigate to the **Plugins** section within the **Portal Builder** section of the side panel.
2. Click "Add Data Source" and select the **Flux** plugin.
3. Take note of your `RELY_API_TOKEN` and `RELY_INTEGRATION_ID`.
4. Install the Helm Chart on your Kubernetes cluster, ensuring the the following:
   * `integration.type` is set to `flux`
   * `integration.executionType` is set to `daemon`
   * `flux.namespaces` is set to the array of namespaces you want to monitor
   * `env.RELY_API_TOKEN` and `env.RELY_INTEGRATION_ID` properly set with the values in the plugin page
5. On successful install, Galaxy will perform the following tasks:

   * Extend your Data Model with Kubernetes Cluster, Kubernetes Namespace, Flux Source, Flux Application and Flux Pipeline blueprints.
   * Pull all available Flux resources in the cluster to backfill your catalog.
   * Monitor Flux reconciliation events in real-time and push information related your workload deployments.

Below is an example command for installing the Helm Chart:

```bash
helm upgrade --install rely-galaxy \
  --set integration.type=flux \
  --set integration.executionType=daemon \
  --set "flux.namespaces={foo,bar}" \
  --set env.RELY_API_TOKEN=rely_api_token \
  --set env.RELY_INTEGRATION_ID=12345678 \
  -n rely-galaxy \
  oci://registry-1.docker.io/devrelyio/galaxy-helm
```

### Additional configuration

By default, standard system Kubernetes namespaces are ignored when collecting Flux resources; this can be changed by setting `env.RELY_INTEGRATION_FLUX_EXCLUDE_SYSTEM_NAMESPACES` to `false`.

In addition to plugin-specific configuration options, you can also configure how often the integration runs by setting `daemonInterval`. See [Self-Hosting Plugins using Galaxy](/plugins-and-automation/self-hosting-plugins-using-galaxy) and check out the [Galaxy - OSS repository](https://github.com/Rely-io/galaxy-oss) for all details on how to configure your integration installation.


# GitHub

Overview

GitHub is a renowned platform for hosting and versioning code, facilitating collaboration among developers. Leverage the power of GitHub's vast repository data within Rely.io for a comprehensive view of your software life-cycle.

## Installation Guide

### Required permissions

During the configuration process, you'll be asked to install and authorize the [Rely.io](http://rely.io/) GitHub App. This app will require specific permissions in your account for the plugin to function properly:\
\
**Read**

<table data-header-hidden><thead><tr><th></th><th width="285"></th><th></th></tr></thead><tbody><tr><td>✅ Actions</td><td>✅ Code</td><td>✅ Issues</td></tr><tr><td>✅ Members</td><td>✅ Metadata</td><td>✅ Pull Requests</td></tr><tr><td>✅ Workflows</td><td></td><td></td></tr></tbody></table>

**Write**

| ✅ Workflows |   |   |
| ----------- | - | - |

{% hint style="info" %}
The necessary permission scopes will be automatically filled in for you so you don't have to worry about that.&#x20;
{% endhint %}

{% hint style="warning" %}
Installing applications in GitHub organizations require administrator permissions. Make sure you have them or request support from your GitHub organization owner.
{% endhint %}

### Steps to Integrate GitHub with Rely.io

1. Go to your Rely.io organization and start by navigating to the [data sources](https://webapp.rely.io/data-model/datasources) page.
2. Click the "*Add Data Source*" button and select "*Github*".<br>

   <figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FNmeyM74aP1uL4ZXfnpoL%2Fgithub%20plugin.png?alt=media&amp;token=70e99781-c064-4724-bd08-29a1a1b2f939" alt=""><figcaption></figcaption></figure>
3. You'll be redirected to GitHub App's integration form. Login to your GitHub account.
4. Install the application in your organization. *This action requires administrator access in the GitHub organization.*
5. You'll be redirected back to the Rely.io.
6. Provide an expressive name to this integration that allows you to easily identify the source, and click "**Submit**".<br>

   <figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2F6anXNPfqzaUBL2wo6Eo1%2Fimage.png?alt=media&amp;token=00ec3c7e-3600-429b-9d20-6f3c64434ada" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To prevent pulling outdated or stale data from your tools and flooding your catalog with unactionable entities, our plugins are set by default with policies to reduce noise.

For instance in the case of Git providers:

* Repositories with no activity over the last 3 months are ignored
* Repositories that have been archived are also ignored
* All entities related to ignored repositories (Pull Requests, Issues, Deployments, etc.) are consequently ignored

To learn more about these policies and how to customize them, read our related [article in our FAQ](/faq#why-cant-i-find-some-entities-in-the-discovery-page).&#x20;
{% endhint %}

After you add the GitHub plugin, an entity discovery run will be triggered. The initial discovery run can take up to a few minutes. By the end of this discovery run:

* New blueprints will be added to your data model
* Entities retrieved from the data source will be added to the [Discovery](https://webapp.rely.io/data-model/discovery) page for you to either approve or reject them

{% hint style="info" %}
The plugin periodically updates all retrieved entities to ensure they stay in sync with their external counterparts.
{% endhint %}

Once the initial discovery run completes successfully you should see your GitHub plugin under the `Active` section of the `data sources` page.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FURQzTURqvnczUD5dYqfI%2Fimage.png?alt=media&amp;token=77b80ede-8c7b-4e43-b3ce-a9ac687953ae" alt=""><figcaption></figcaption></figure>

The next step is to get the GitHub entities synced into your Service Catalog. Check our [official guidance](/getting-started-guide/import-services-into-the-service-catalog) on how to do it.


# GitLab

## Overview

GitLab is an all-in-one CI/CD and source code management platform that streamlines software development. Benefit from GitLab's vast repository data within Rely.io for a comprehensive view of your software lifecycle.

## Installation Guide

Integrate GitLab with your Rely.io platform to centralize your code repositories, merge requests, and much more. By integrating GitLab, you can better manage your services, streamline your DevOps processes, and ensure that your teams are always on the same page.

### Required Permissions for GitLab plugin

During the configuration process, you'll be asked to provide an Access Token. This token must have the following permissions in order for the Rely.io GitLab plugin to work.&#x20;

\
**Read**

<table data-header-hidden><thead><tr><th width="156"></th><th width="566"></th></tr></thead><tbody><tr><td>✅ API</td><td>Enables Rely.io to make API calls to GitLab for various activities like fetching repositories, branches, and merge requests.</td></tr><tr><td>✅ Repository</td><td>Allows Rely.io to pull repository metadata.</td></tr></tbody></table>

{% hint style="info" %}
&#x20;The following steps  will guide you through the process of generating this Access Token.
{% endhint %}

### Steps to Integrate GitLab with Rely.io

#### Step 1: Navigate to your organization's GitLab Group page&#x20;

Start by logging into GitLab and navigating to your organization's group page (e.g. <https://gitlab.com/detech.ai>). In the side panel expand the *Settings* sub-menu and click *Access tokens*.&#x20;

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FkPqKHSXQPyCVaX3X3s74%2FUntitled%20Diagram.drawio-redacted_dot_app.png?alt=media&amp;token=e3792bb9-5672-4ac7-876c-ad6e90fac153" alt=""><figcaption><p>Navigate to Access Tokens page</p></figcaption></figure>

{% hint style="warning" %}
This option will only be available if you have the required permissions. To view and create access tokens at the group level, you must have one of the following roles within the group:

* Owner
* Maintainer
  {% endhint %}

#### Step 2: Generate GitLab Group Access Token

1. Click on `Add new token`.
2. We recommend assigning the **role of Owner** for this token to ensure full access to all group-related data, which is crucial for seamless integration. Setting the role to a lower level, such as **Guest**, may result in limited functionality, such as restricted access to private projects, repositories, and CI/CD pipelines. This could prevent essential data from being retrieved and hinder integration performance.&#x20;
3. Check the required scopes (`read_api`, `read_repository`) for the token.
4. Name your token for easier future reference, such as "Rely.io GitLab Integration".
5. Click on `Create group access token`.

{% hint style="info" %}
In case these steps are not clear follow GitLab's official documentation on how to create group
{% endhint %}

Once the token is created, make sure to copy and store it securely; you'll need it for the next steps.

#### Step 3: Connect GitLab to Rely.io

1. Open Rely.io and select `Plugins` from with the `Portal Builder`.
2. Click the `Add Data Source` button and select `GitLab` from the dropdown.
3. A prompt will appear, asking for details to establish the integration.
   * **Plugin Name**: Provide a name for the GitLab plugin.
   * **Organization Name:** Name of your GitLab organization which you can copy from the url (e.g. <https://gitlab.com/[YOUR_ORGANIZATION_NAME]>)
   * **Access Token**: Paste the GitLab Access token generated in Step 2.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2FXCa2tg3bfx39ZVzhvuGA%2Fimage.png?alt=media&amp;token=6da1318c-b548-4a2b-a442-1fd5d615ee85" alt=""><figcaption><p>Configure GitLab plugin</p></figcaption></figure>

{% hint style="info" %}
To prevent pulling outdated or stale data from your tools and flooding your catalog with unactionable entities, our plugins are set by default with policies to reduce noise.

For instance in the case of Git providers:

* Repositories with no activity over the last 3 months are ignored
* Repositories that have been archived are also ignored
* All entities related to ignored repositories (Merge Requests, Issues, Deployments, etc.) are consequently ignored
  {% endhint %}

After you add the GitLab plugin, an entity discovery run will be triggered. The initial discovery run can take up to a few minutes. By the end of this discovery run:

* New blueprints will be added to your data model
* Entities retrieved from the data source will be added to the [Discovery](https://webapp.rely.io/data-model/discovery) page for you to either approve or reject them

{% hint style="info" %}
The plugin periodically updates all retrieved entities to ensure they stay in sync with their external counterparts.
{% endhint %}

Once the initial discovery run completes successfully you should see your GitLab plugin under the `Active` section of the `data sources` page.

<figure><img src="https://1179008450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eBCWu9rFSzq3ahnNrmL%2Fuploads%2F1fFNxl4TRxaAUscmopVI%2Fplugin-catalog-gitlab.png?alt=media&amp;token=8c8db951-8679-4bc9-a782-a47497005927" alt=""><figcaption><p>Active plugins list</p></figcaption></figure>

The next step is to get the GitLab entities imported into your Service Catalog. Check our [official guidance](/getting-started-guide/import-services-into-the-service-catalog) on how to do it.


# Google Cloud Platform (GCP)

{% hint style="info" %}
This plugin is part of Pro and Enterprise plan only
{% endhint %}

## Overview

By integrating GCP's monitoring solutions with Rely.io's platform, you can tap into the extensive data collected by GCP and bring it into Rely's comprehensive environment. This allows for a consolidated view of your cloud infrastructure and the applications running on it.

Whether you're using Compute Engine, Kubernetes Engine, or any other GCP service, this integration ensures that you can keep a close eye on your deployments while benefiting from Rely.io's advanced analytics.

## Installation Guide

To integrate your account with Google Cloud Platform (GCP), navigate to the Plugins page, click "Add Data Source" and select GCP.

This will prompt a modal to appear asking you for the information necessary to successfully integrate GCP with your Rely.io account. Rely's GCP plugin relies a Service Account JSON Key File, to create one follow this steps:

1. Start by enabling GCP's Cloud Asset API if it's not already enabled. You can do so [here](https://console.cloud.google.com/marketplace/product/google/cloudasset.googleapis.com?q=search\&referrer=search\&hl=en\&project=glossy-topic-407818\&pli=1\&login=true)
2. From your Cloud Console, access the "*Service Accounts"* page
3. Select "+ Create Service Account"
4. Fill in the essential Service account details
   1. Provide a name for the service account (e.g. Rely.io Integration)
   2. Click to auto-generate an account ID
   3. (optional) Provide a small description for your service account (e.g. Service account used to provide Rely.io the necessary permissions to pull GCP data)
5. Hit "Create and Continue" to go to the form's second step and assign the following permissions to the Service Account:
   * Monitoring Viewer
   * Compute Viewer
   * Cloud Asset Viewer
6. Hit "Done" (step 3 is not required)
7. You should be redirected to the list of all your Service Accounts. Click the "Actions" button of the Service Account you just created and click "Manage keys"
8. Click "Add Key" and select the "JSON" key type. This should automatically download your newly created JSON service account key file.

Go back to the Rely.io. You can upload this JSON file in the last step of your GCP plugin creation form.

After you submit your form, an entity discovery run will be kickstarted that can take a few minutes. By the end of this discovery run:

* New blueprints will be added to your data model
* Entities will be queries from the data-source and added to your software catalog
* These entities will be periodically updated to ensure they remain in sync with their external counter-parts


# Grafana Cloud

{% hint style="info" %}
This plugin is part of Pro and Enterprise plan only
{% endhint %}

## Overview

Grafana Cloud is a powerful service that simplifies the process of collecting, visualising, and analysing data.

Integrating Grafana Cloud with Rely.io enables you to ingest metrics from Grafana, displaying them within Rely's software catalog in relevant contexts. This integration allows for a seamless and efficient monitoring experience, ensuring that metrics from Grafana Cloud are readily accessible and actionable within the Rely platform.

By utilizing this integration, you can leverage Grafana's extensive data visualization capabilities alongside Rely's contextual insights, enhancing your ability to understand and optimize your systems.

## Installation Guide

To get started with the Grafana Cloud integration, follow the steps below.

#### 1. Generate a Service Account Token

Before you can connect Rely.io to Grafana Cloud, you need to generate the required Service Account Token. The following guide was based on the [official documentation](https://grafana.com/docs/grafana/latest/administration/service-accounts/#to-create-a-service-account) provided by Grafana.

Create a service account with the required Roles

1. Sign in to Grafana and click **Administration** in the left-side menu.
2. Click **Users and access**.
3. Click **Service accounts**.
4. Click **Add service account** (E.g. relyio-service-account)
5. Enter a **Display name**.
6. In the **Roles** select\*\*:\*\*
   1. Basic roles: "**Viewer"**
   2. Fixed roles: **"Data Sources > reader"**
7. Click **Create**.

Generate an access token:

1. Click the service account which that you just created
2. Click **Add service account token**.
3. Enter a name for the token (E.g. relyio-plugin-token)
4. (optional) **Set an expiration date** for the token.
5. Click **Generate token.** Be cautious, this token will not be displayed again, ensure to copy and securely store it immediately.

#### 3. Connect to the Rely Platform

Now that you have generated the necessary information, you can proceed to connect your Grafana Cloud account with Rely.

Open the Rely platform and start by navigating to the data-sources page. Click the "Add Data Source" button and select "Grafana Cloud". This will prompt a modal requesting the required information for a successfully integration.

* **Collector Name**: Enter a name for the collector.
* **Service Account Token**: Paste here the token generated in the previous step.

After you submit your form, you will be able to use the "metric" data-types to import and visualize your Grafana Metrics within Rely's Software Catalog.


# Incident.io

*Coming Soon!*


# Instana

*Coming Soon!*


# Jira

{% hint style="info" %}
This plugin is part of Pro and Enterprise plan only
{% endhint %}

## Overview

Jira, by Atlassian, is a widely-used project and issue management platform. When integrated with Rely.io, it can provide additional dimensions of insights, such as customer-facing incidents, security tickets, and ongoing projects. Leveraging Jira data within Rely.io can help in achieving better incident management and project tracking.

Rely.io fetches data directly from Jira, including Projects, Issues, Users, and Groups, ensuring regular synchronization on an hourly basis. Additionally, to achieve real-time data updates, this plugin supports webhooks as outlined in Step 3 of this guide.

## Installation Guide

**Step 1: Generate a Jira API Token (official docs** [**here**](https://id.atlassian.com/manage-profile/security/api-tokens)**).**

1. Log into your Jira Cloud account.
2. Navigate to `Account settings` → `Security` → `API tokens`.
3. Click `Create and manage API tokens`.
4. Name your token, for example, "Rely.io Integration", and click `Create`.
5. Copy and securely store the API token generated.

**Step 2: Add Jira to Rely.io Settings**

1. Open Rely.io and navigate to `Settings` → `Data Sources`.
2. Click `Add Data Source` and choose `Jira`.
3. A form will appear for the Jira Cloud integration:
   * **Plugin Name**: Assign a name for the Jira data source collector.
   * **Jira API Token**: Paste the token you generated in Step 1.
   * **Jira Username Email**: Enter the email address associated with the Jira API Token (should match the email used in Jira settings on Step 1.
   * **Webhook Token**: This token authenticates webhook requests from Jira to Rely.io. If you want to enable webhook implementation, securely store this token for use in Step 3, as you won't be able to view it again in the future. You can also generate a new token and paste it in this field.

Click `Create` to finalize the integration.

**Step 3: Configure Webhooks in Jira**

1. Go to **Jira administration** → **System** → **Webhooks**.
2. Click **Create a Webhook**.
3. Fill in the details:
   * **Name**: Set a name like "Rely.io Integration Webhook".
   * **URL**: Get the webhook URL from Rely.io. Go to [Rely.io Data Sources](https://webapp.rely.io/data-model/datasources), select the Jira plugin and click "View details". The URL format should be `https://magneto.rely.io/api/v1/webhooks/jira?plugin_id=<plugin_identifier>`.
   * **Secret**: Use the webhook token generated in Step 3.
4. Under **Events**, select the following checkboxes:
   * **Issue related events**: Issue created, updated, deleted.
   * **User related events**: User created, deleted, updated.
   * **Project related events**: Project created, updated, deleted
5. Click **Create** at the bottom of the page.

After you submit your form, an entity discovery run will be kickstarted that can take a few minutes. By the end of this discovery run:

* New blueprints will be added to your data model
* Entities representing Jira Projects, Users, Issues and Groups, will be added your software catalog
* These entities will be hourly updated  to ensure they remain in sync with their external counter-parts
* With webhooks enabled the changes in Jira will be immediately available in your software catalog.
* Only issues 30 days old will be added to your data model from the moment you setup this integration.


# Kubernetes

{% hint style="info" %}
This plugin is part of Pro and Enterprise plan only
{% endhint %}

### **Introduction**

This guide provides instructions for integrating the [Rely.io](http://rely.io) Kubernetes plugin into your Kubernetes cluster. The integration involves two primary steps:

1. Retrieving the API token from [Rely.io](http://rely.io).
2. Installing the [Rely.io](http://rely.io) Kubernetes plugin using Helm.

### **Prerequisites**

* Access to your Kubernetes cluster via **`kubectl`**.
* Helm installed on your local machine or wherever you deploy Helm charts.

### **Step 1: Retrieve Your API Token**

#### **Obtaining the Token**

1. Navigate to Rely.io > Data Model > Plugins
2. Locate the OOTB plugin for Rely's Public API, click "View Details"
3. Hit "Generate an API key" which will copy a token onto your clipboard, you'll use it in the next step of this guide.

#### **Creating a Secret in Kubernetes**

Store the API token in your Kubernetes cluster as a secret.

```java
kubectl create secret generic relyio-api-token \\
  --namespace rely-integrations \\
  --from-literal=API_TOKEN="YOUR-API-TOKEN"
```

Replace `YOUR-API-TOKEN` with the actual API token you obtained from [Rely.io](http://rely.io).

### **Step 2: Install the** [**Rely.io**](http://rely.io) **Kubernetes Plugin**

#### **Adding the Helm Repository**

Add the [Rely.io](http://rely.io) plugin repository to your Helm setup. Please note that the repository endpoint provided below is a placeholder and should be replaced with the actual repository URL.

#### Command:

```bash
helm repo add relyio https://relyio-plugin-kubernetes-detech-ai-61649e8973c3604c946bff460f81.gitlab.io
```

#### **Installing the Plugin**

Install the [Rely.io](http://rely.io) Kubernetes plugin in your cluster under the **`rely-integrations`** namespace.

```bash
helm upgrade --install relyio-plugin-kubernetes \\
  relyio/relyio-plugin-kubernetes \\
  -n rely-integrations
```

### **Conclusion**

You have successfully integrated the [Rely.io](http://rely.io) Kubernetes plugin into your cluster and you should be able to see it in the "Plugins" page in Rely.

This plugin will enable your Kubernetes environment to communicate effectively with [Rely.io](http://rely.io) services. For any issues or further assistance, consult the provided links or contact support.


# New Relic

{% hint style="info" %}
This plugin is part of Pro and Enterprise plan only
{% endhint %}

## Overview

New Relic is an innovative observability platform that offers comprehensive insights into your application's performance and system health. By integrating New Relic with Rely.io's platform, you can utilize the monitoring data collected by New Relic within Rely's platform.

## Installation Guide

To get started with the New Relic integration, follow the steps below:

#### 1. Generate API key

Before you can connect Rely to New Relic, you need to generate the an API Key. The following guide was based on the [official documentation](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/) provided by New Relic. Start by accessing the [API keys UI page](https://one.newrelic.com/launcher/api-keys-ui.api-keys-launcher).

1. Click the "Create a key" button which will prompt a creation form
2. Select the `Account Id` you which to integrate with, this should reference the account from that hosts the telemetry data you wish to use in the Rely platform
3. Select `Key Type: User`. This key type will allow Rely to use [NerdGraph](https://docs.newrelic.com/docs/apis/intro-apis/introduction-new-relic-apis/#graphql) and perform NRQL queries. To learn more about key types read the [official docs](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#key-details).
4. Provide your key with a meaningful name like: `Rely.io Access Key`.
5. Submit the form

Afterwards a new entry will be added to the list of API keys. For the third step of this guide you'll need:

1. The `Account Id` of the key you have just generated.
2. The `API Key Value`, which you can access by clicking the options button of the new row and clicking "Copy Key"

#### 2. Check if your account is based in EU region

To integrate with Rely you'll need to know if your New Relic account is based in the EU region's data center or not. Both are viable, it's just a matter of knowing.

Use either of these options to learn that:

* In APM, mouse over the application name to view the URL. If it begins with `rpm.eu.newrelic.com/`, it is an EU-based account.
* Check your license key. If it begins with `EU`, it is an EU-based account.

Or reference the [official documentation](https://docs.newrelic.com/docs/accounts/accounts-billing/account-setup/choose-your-data-center/#verifying-account).

#### 3. Connect to the Rely Platform

Now, you can proceed to connect your New Relic account with Rely.

Open the Rely platform and start by navigating to the data-sources page. Click the "Add Data Source" button and select "New Relic".

This will prompt a modal to appear asking you for the information necessary to successfully integrate New Relic with your Rely.io account.

Fill in the required input fields:

* **Collector Name**: Enter a name for the collector.
* **Account ID**: Paste the Account Id referenced in the first step.
* **API Key**: Paste the API key generated in the first step.
* **EU Data Center**: If you have a New Relic EU region account, check the EU Data Center box.

Click "Create" to finish the integration process.

After you submit your form, an entity discovery run will be kickstarted that can take a few minutes. By the end of this discovery run:

* New blueprints will be added to your data model
* Entities will be queries from the data-source and added to your software catalog
* These entities will be periodically updated to ensure they remain in sync with their external counter-parts

Congratulations! You have successfully set up the New Relic integration for Rely.io's platform.


# Nobl9

## Installation Guide

To get started with the Nobl9 integration, follow the steps below.

#### 1. Generate an Access Key

Before you can connect Rely.io to Nobl9, you need to generate the required Access Key credentials. The following guide was based on the [official documentation](https://docs.nobl9.com/Getting_Started/#access-keys) provided by Nobl9.

1. Log in to [Nobl9](https://app.nobl9.com/) UI.
2. Go to **Settings** > **Access Keys**. Click **Create Access Key**.
3. An access key will be generated, comprising an organization ID, a client ID, and a client secret. All these fields are essential for the next step of this guide. Be cautious: **the client secret will not be displayed again** - ensure to copy and securely store it immediately.

#### 3. Connect to the Rely Platform

Now that you have generated the necessary information, you can proceed to connect your Nobl9 account with Rely.

Open the Rely platform and start by navigating to the data-sources page. Click the "Add Data Source" button and select "Nobl9". This will prompt a modal requesting the required information for a successfully integration.

* **Collector Name**: Enter a name for the collector.
* **Organization ID**: Paste the Organization Identifier generated in the previous step.
* **Client ID:** Paste the client ID generated in the previous step.
* **Client Secret:** Paste the client Secret generated in the previous step.

After you submit your form, you will be able to use the "slo" data-type to start import and visualize your Nobl9 SLOs within Rely's Software Catalog.


# Notion

{% hint style="info" %}
This plugin is part of Pro and Enterprise plan only
{% endhint %}

*Coming Soon!*


# OpsGenie

{% hint style="info" %}
This plugin is part of Pro and Enterprise plan only
{% endhint %}

## Installation Guide

### Setup

#### Step 1: Generate an Opsgenie API Key (official docs [here](https://support.atlassian.com/opsgenie/docs/api-key-management/)).

1. Log in to your Opsgenie account and navigate to `Settings` → `API Key Management` (if you cannot find this option in your side bar under `App Settings` you probably do not enough the necessary permissions to create one).
2. Click the `Add New API Key` button.
3. Enter a description for the API Key, for instance, "Rely.io Integration."
4. Set the API key to have `Read` and `Configuration` access, as needed for the integration.
5. Click `Create Key` and make sure to copy and store the generated API Key securely.

#### Step 2: Configure Opsgenie in Rely.io

1. Open the Rely.io application and go to `Settings` → `Data Sources`.
2. Click on the `Add Data Source` button and select `Opsgenie`.
3. A form will appear asking for details to complete the integration.
   * **Collector Name**: Assign a name for the PagerDuty data collector.
   * **App Base URL:** Copy the base url of your Opsgenie account (e.g. <https://sunsy.app.opsgenie.com>)
   * **API Key**: Paste the API Key you generated in Step 1.

Click on `Create` to establish the integration. Your plugin should now be listed in the `Active` section of your `Data Sources`.

After you submit your form, an entity discovery run will be kickstarted that can take a few minutes. By the end of this discovery run:

* New blueprints will be added to your data model
* Entities will be queries from the data-source and added to your software catalog
* These entities will be periodically updated to ensure they remain in sync with their external counter-parts


# PagerDuty

{% hint style="info" %}
This plugin is part of Pro and Enterprise plan only
{% endhint %}

## Overview

PagerDuty is an alerting and incident management platform, known for its robust on-call scheduling, escalation policies, and real-time alerts. By integrating PagerDuty with Rely.io, you can automate the incident response and synchronize your on-call information with your service catalog, thus ensuring smoother operations and quicker issue resolution.

## Installation Guide

### Setup

#### Step 1: Generate a PagerDuty API Key (official docs [here](https://support.pagerduty.com/docs/api-access-keys)).

1. Log in to your PagerDuty account and navigate to `Integrations` → `API Access Keys`.
2. Click the `Create New API Key` button.
3. Enter a description for the API Key, for instance, "Rely.io Integration."
4. Set the API key to have `Read` access, as needed for the integration.
5. Click `Create Key` and make sure to copy and store the generated API Key securely.

#### Step 2: Configure PagerDuty in Rely.io

1. Open the Rely.io application and go to `Settings` → `Data Sources`.
2. Click on the `Add Data Source` button and select `PagerDuty`.
3. A form will appear asking for details to complete the integration.
   * **Collector Name**: Assign a name for the PagerDuty data collector.
   * **API Key**: Paste the API Key you generated in Step 1.

Click on `Create` to establish the integration. Your PagerDuty collector should now be listed in the `Active` section of your `Data Sources`.

After you submit your form, an entity discovery run will be kickstarted that can take a few minutes. By the end of this discovery run:

* New blueprints will be added to your data model
* Entities will be queries from the data-source and added to your software catalog
* These entities will be periodically updated to ensure they remain in sync with their external counter-parts




---

[Next Page](/llms-full.txt/1)