Rely.io
  • ๐Ÿ“ŒWhat is Rely.io?
  • ๐Ÿ’กHow Rely.io works
  • ๐Ÿ“‘Getting Started Guide
    • Create an account for your organization
    • Add your first plugin
    • Import services into the Service Catalog
    • Make the Software Catalog your own
    • What's Next?
  • ๐ŸŒˆBasic Concepts
    • Entities
    • Blueprints
    • Property Data Types
    • Catalogs
    • Data Model
    • Plugins
    • User Blueprints vs Plugin Blueprints
    • Actions and Automations
      • Automation Rules
      • Self-Service Actions
    • Home Pages
    • Scorecards
  • ๐Ÿ“šGuides & Tutorials
    • Enhancing Deployment Visibility through Gitlab Pipelines and Rely's API
  • ๐Ÿ–ฅ๏ธSoftware Catalog
    • Overview and Use Cases
    • Usage Guide
      • Creating a new Entity
      • Updating an Entity
      • Tracking Entity Changes
      • Customizing an Entity's Page
      • Customizing a Catalog
      • Creating a new Blueprint & Catalog
      • Updating a Blueprint
      • Tracking Blueprint Changes
    • Relevant Guides
    • Troubleshooting
  • ๐Ÿฅ‡Scorecards
    • Overview and Use Cases
    • Usage Guide
      • Creating a Scorecard
      • Updating a Scorecard
      • Evaluating Performance
    • Scorecard Examples
      • Production Readiness Scorecard Example
      • DORA Metrics Scorecard Example
      • Operational Maturity Example
  • ๐ŸŽจHome Pages
    • Overview and Use Cases
    • Usage Guide
      • Creating a New Tab
  • โšกSelf-Service Actions
    • Overview and Use Cases
    • Usage Guide
      • Configuring your Self Service Agent
      • Managing your Actions Catalog
      • Self-Service Actions as Code
      • Running Actions
      • Tracking Action Runs
  • โ†—๏ธPlugins & Automation
    • What happens when you install a Plugin?
    • Self-Hosting Plugins using Galaxy
    • ๐Ÿค–Automation Rules
      • Overview and Use Cases
      • Usage Guide
        • Creating an Automation Rule
        • Updating an Automation Rule
        • Tracking Automation Changes
        • Managing Automation Suggestion
    • ๐Ÿ”ŒPlugin Installation Guides
      • โญAWS
      • Bitbucket
      • โญFlux
      • GitHub
      • GitLab
      • โญGoogle Cloud Platform (GCP)
      • โญKubernetes
      • โญOpsGenie
      • โญPagerDuty
      • โญSnyk
      • โญSonarQube
  • ๐ŸŒPublic API
    • Audit Logs
    • Automations & Self-Service Actions
    • Automation Suggestions
    • Blueprints
    • Dashboards & Views
    • Entities
    • Scorecards
    • Self-Service Action Runs
    • Time Series
    • Users
    • Webhooks
  • โš™๏ธInvite Users
  • ๐Ÿ›ก๏ธSecurity & Compliance
    • Single Sign-On (SSO)
      • SAML with Google Workspace
      • SAML with Microsoft Entra ID
      • SAML with Okta
      • OIDC with Okta
      • OIDC with Google Workspace
  • ๐ŸฅTroubleshooting
  • โ“FAQ
Powered by GitBook
On this page
  • Step 1 - Generate a Rely API key
  • Step 2 - Set it as Variable in your CI/CD Pipeline
  • Step 3 - Add Jobs to your CI/CD Pipeline
  • Relevant API Endpoints for Rely Integration
  • E.g. 1 Creating a Deployment and Relating it to Gitlab Pipeline thatโ€™s ingested by Relyโ€™s Gitlab Plugin
  • E.g. 2 Updating a specific Serviceโ€™s OpenAPI schema
  • E.g. 3 Fleshed-out example for creating a Deployment Entity during Merge Request Pipelines to Main

Was this helpful?

  1. Guides & Tutorials

Enhancing Deployment Visibility through Gitlab Pipelines and Rely's API

PreviousGuides & TutorialsNextSoftware Catalog

Last updated 1 year ago

Was this helpful?

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.

Click on โ€œView detailsโ€ to proceed:

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.

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.

  • Group Level: Apply variables to all projects within a group in the groupโ€™s settings.

  • Instance Level: Configure variables for all projects in your GitLab instance in the instanceโ€™s settings.

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โ€.

  • Description: Provide a clear description of the variable's purpose (e.g., "API token for interacting with 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 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.

E.g. 1 Creating a Deployment and Relating it to Gitlab Pipeline thatโ€™s ingested by Relyโ€™s Gitlab Plugin

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

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.

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"
๐Ÿ“š