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.

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"