DX| 29-06-2026 | Release

.github/workflows/back-merge-pr.yml

@@ -0,0 +1,59 @@
+# Opens a PR from master → development after changes land on master (back-merge).
+#
+# Org/repo Settings → Actions → General → Workflow permissions: read and write
+# (so GITHUB_TOKEN can create pull requests). Or use a PAT in secret GH_TOKEN.
+
+name: Back-merge master to development
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  open-back-merge-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Open back-merge PR if needed
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          git fetch origin development master
+
+          MASTER_SHA=$(git rev-parse origin/master)
+          DEV_SHA=$(git rev-parse origin/development)
+
+          if [ "$MASTER_SHA" = "$DEV_SHA" ]; then
+            echo "master and development are at the same commit; nothing to back-merge."
+            exit 0
+          fi
+
+          EXISTING=$(gh pr list --repo "${{ github.repository }}" \
+            --base development \
+            --head master \
+            --state open \
+            --json number \
+            --jq 'length')
+
+          if [ "$EXISTING" -gt 0 ]; then
+            echo "An open PR from master to development already exists; skipping."
+            exit 0
+          fi
+
+          gh pr create --repo "${{ github.repository }}" \
+            --base development \
+            --head master \
+            --title "chore: back-merge master into development" \
+            --body "Automated back-merge after changes landed on \`master\`. Review and merge to keep \`development\` in sync."
+
+          echo "Created back-merge PR master → development."

.github/workflows/check-version-bump.yml

@@ -0,0 +1,76 @@
+# Runs only when production code under lib/ changes. Version must be > latest v* tag (not vs base branch).
+
+name: Check Version Bump
+
+on:
+  pull_request:
+
+jobs:
+  check-version-bump:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Validate version and changelog updates
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          VERSION_FILE="lib/contentstack_utils/version.rb"
+          CHANGELOG_FILE="CHANGELOG.md"
+          BASE_SHA="${{ github.event.pull_request.base.sha }}"
+          HEAD_SHA="${{ github.event.pull_request.head.sha }}"
+
+          mapfile -t CHANGED_FILES < <(git diff --name-only "$BASE_SHA" "$HEAD_SHA")
+          if [ "${#CHANGED_FILES[@]}" -eq 0 ]; then
+            echo "No changed files detected."
+            exit 0
+          fi
+
+          is_production_source_change() {
+            local f="$1"
+            [[ "$f" == lib/* ]]
+          }
+
+          has_source_changes=false
+          for file in "${CHANGED_FILES[@]}"; do
+            if is_production_source_change "$file"; then
+              has_source_changes=true
+              break
+            fi
+          done
+
+          if [ "$has_source_changes" = false ]; then
+            echo "Skipping: no lib/ production code changes."
+            exit 0
+          fi
+
+          changed_file() {
+            local target="$1"
+            for file in "${CHANGED_FILES[@]}"; do
+              if [ "$file" = "$target" ]; then
+                return 0
+              fi
+            done
+            return 1
+          }
+
+          changed_file "$VERSION_FILE" || { echo "Version bump required in $VERSION_FILE."; exit 1; }
+          changed_file "$CHANGELOG_FILE" || { echo "Matching changelog update required in $CHANGELOG_FILE."; exit 1; }
+
+          head_version=$(sed -nE 's/.*VERSION\s*=\s*["'"'"']([^"'"'"']+)["'"'"'].*/\1/p' "$VERSION_FILE" | sed -n '1p')
+          CHANGELOG_HEAD=$(sed -nE 's/^## v?\[?([0-9]+\.[0-9]+\.[0-9]+).*/\1/p' "$CHANGELOG_FILE" | head -1)
+
+          [ -n "$CHANGELOG_HEAD" ] || { echo "::error::Could not find a top changelog heading like '## vX.Y.Z' in $CHANGELOG_FILE."; exit 1; }
+          [ "$CHANGELOG_HEAD" = "$head_version" ] || { echo "::error::$CHANGELOG_FILE top version ($CHANGELOG_HEAD) does not match project version ($head_version)."; exit 1; }
+
+          latest_tag=$(git tag --list 'v*' --sort=-version:refname | sed -n '1p')
+          latest_version="${latest_tag#v}"
+          [ -n "$latest_version" ] || latest_version="0.0.0"
+
+          version_gt() {
+            python3 -c 'import sys;v=lambda s:[int(x) if x.isdigit() else 0 for x in (s.strip().lstrip("v").split("-",1)[0].split("+",1)[0].split(".")+["0","0","0"])[:3]];print("true" if v(sys.argv[1])>v(sys.argv[2]) else "false")' "$1" "$2"
+          }
+
+          [ "$(version_gt "$head_version" "$latest_version")" = "true" ] || { echo "Version must be greater than latest tag version ($latest_version). Found $head_version."; exit 1; }

.github/workflows/release-gem.yml

@@ -6,6 +6,7 @@ on:
 
 jobs:
   build:
+    if: ${{ startsWith(github.event.release.tag_name, 'v') && !github.event.release.draft }}
     name: Build + Publish
     runs-on: ubuntu-latest
     permissions:
@@ -14,6 +15,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
+      with:
+        ref: ${{ github.event.release.tag_name }}
     - name: Set up Ruby 2.7
       uses: ruby/setup-ruby@v1
       with:

.gitignore

@@ -8,4 +8,6 @@ coverage
 .DS_Store
 .bundle/
 **/rspec_results.html
-.dccache
+.dccache
+vendor/
+lib/contentstack_utils/assets/regions.json

.ruby-version

@@ -1 +1 @@
-3.1.4
+3.3.11

CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog
 
-## [1.2.5](https://github.com/contentstack/contentstack-utils-ruby/tree/v1.2.5) (2026-06-24)
+## [1.3.0](https://github.com/contentstack/contentstack-utils-ruby/tree/v1.3.0) (2026-06-29)
+  - Added `ContentstackUtils::Endpoint.get_contentstack_endpoint` for dynamic endpoint resolution based on region and service.
+  - Added `ContentstackUtils.get_contentstack_endpoint` as a backward-compatible proxy.
+  - Added `ContentstackUtils::Endpoint.refresh_regions` for manual region metadata refresh.
+  - Added runtime fallback to automatically download `regions.json` from the Contentstack Regions Registry when not present locally.
   - Fixed security vulnerabilities: upgraded yard to 0.9.44 (Directory Traversal) and concurrent-ruby to 1.3.7 (Infinite loop, Improper Locking, Wrap-around Error).
 
 ## [1.2.4](https://github.com/contentstack/contentstack-utils-ruby/tree/v1.2.4) (2026-04-15)

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    contentstack_utils (1.2.5)
+    contentstack_utils (1.3.0)
       activesupport (>= 7.0, < 8)
       nokogiri (~> 1.19, >= 1.19.2)
 
@@ -38,21 +38,21 @@ GEM
       concurrent-ruby (~> 1.0)
     logger (1.7.0)
     minitest (5.27.0)
-    nokogiri (1.19.2-aarch64-linux-gnu)
+    nokogiri (1.19.3-aarch64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.19.2-aarch64-linux-musl)
+    nokogiri (1.19.3-aarch64-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.19.2-arm-linux-gnu)
+    nokogiri (1.19.3-arm-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.19.2-arm-linux-musl)
+    nokogiri (1.19.3-arm-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.19.2-arm64-darwin)
+    nokogiri (1.19.3-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.19.2-x86_64-darwin)
+    nokogiri (1.19.3-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.19.2-x86_64-linux-gnu)
+    nokogiri (1.19.3-x86_64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.19.2-x86_64-linux-musl)
+    nokogiri (1.19.3-x86_64-linux-musl)
       racc (~> 1.4)
     public_suffix (7.0.5)
     racc (1.8.1)

lib/contentstack_utils/endpoint.rb

@@ -0,0 +1,96 @@
+require 'json'
+require 'net/http'
+require 'uri'
+
+module ContentstackUtils
+  module Endpoint
+    REGIONS_URL = 'https://artifacts.contentstack.com/regions.json'
+    REGIONS_FILE = File.expand_path('../assets/regions.json', __FILE__)
+
+    @regions_data = nil
+
+    class << self
+      def get_contentstack_endpoint(region: 'us', service: '', omit_https: false)
+        raise ArgumentError, 'Empty region provided' if region.nil? || region.to_s.strip.empty?
+
+        normalized = region.to_s.strip.downcase
+        regions = load_regions
+
+        region_row = find_region_by_id_or_alias(regions, normalized)
+        raise ArgumentError, "Invalid region: #{region}" if region_row.nil?
+
+        endpoints = region_row['endpoints']
+
+        if service.nil? || service.to_s.strip.empty?
+          return omit_https ? strip_https_from_map(endpoints) : endpoints.dup
+        end
+
+        url = endpoints[service.to_s]
+        raise ArgumentError, "Service \"#{service}\" not found for region \"#{region}\"" if url.nil?
+
+        omit_https ? strip_https(url) : url
+      end
+
+      def refresh_regions
+        download_and_save(REGIONS_FILE)
+        @regions_data = nil
+        load_regions
+        true
+      end
+
+      def reset_cache
+        @regions_data = nil
+      end
+
+      private
+
+      def load_regions
+        return @regions_data if @regions_data
+
+        unless File.exist?(REGIONS_FILE)
+          download_and_save(REGIONS_FILE)
+        end
+
+        raw = File.read(REGIONS_FILE)
+        parsed = JSON.parse(raw)
+        raise RuntimeError, 'Invalid regions data: missing "regions" key' unless parsed.is_a?(Hash) && parsed['regions']
+
+        @regions_data = parsed['regions']
+      rescue JSON::ParserError => e
+        raise RuntimeError, "Failed to parse regions data: #{e.message}"
+      rescue Errno::ENOENT => e
+        raise RuntimeError, "Failed to read regions file: #{e.message}"
+      end
+
+      def download_and_save(dest)
+        uri = URI.parse(REGIONS_URL)
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', open_timeout: 30, read_timeout: 30) do |http|
+          http.get(uri.request_uri)
+        end
+
+        raise RuntimeError, "Failed to download regions: HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        parsed = JSON.parse(response.body)
+        raise RuntimeError, 'Downloaded regions data is invalid' unless parsed.is_a?(Hash) && parsed['regions']
+
+        FileUtils.mkdir_p(File.dirname(dest))
+        File.write(dest, JSON.pretty_generate(parsed))
+      rescue StandardError => e
+        raise RuntimeError, "Failed to fetch region metadata: #{e.message}"
+      end
+
+      def find_region_by_id_or_alias(regions, input)
+        regions.find { |r| r['id'] == input } ||
+          regions.find { |r| r['alias']&.any? { |a| a.downcase == input } }
+      end
+
+      def strip_https(url)
+        url.sub(%r{\Ahttps?://}, '')
+      end
+
+      def strip_https_from_map(endpoints)
+        endpoints.transform_values { |url| strip_https(url) }
+      end
+    end
+  end
+end

lib/contentstack_utils/utils.rb

@@ -1,6 +1,7 @@
 require_relative './model/options.rb'
 require_relative './model/metadata.rb'
 require_relative './support/helper.rb'
+require_relative './endpoint.rb'
 require 'nokogiri'
 
 module ContentstackUtils
@@ -136,6 +137,10 @@ def self.json_doc_to_html(node, options, callback)
         return nil
     end
 
+    def self.get_contentstack_endpoint(region: 'us', service: '', omit_https: false)
+        Endpoint.get_contentstack_endpoint(region: region, service: service, omit_https: omit_https)
+    end
+
     module GQL
         include ContentstackUtils
         def self.json_to_html(content, options)

lib/contentstack_utils/version.rb

@@ -1,3 +1,3 @@
 module ContentstackUtils
-    VERSION = "1.2.5"
+    VERSION = "1.3.0"
 end

skills/code-review/SKILL.md

@@ -33,7 +33,7 @@ description: Use when reviewing or preparing a PR for this gem—behavior, tests
 
 ### Process
 
-- Respect **CODEOWNERS** and branch policy (**`master`** vs **`staging`**) described in [dev-workflow](../dev-workflow/SKILL.md)
+- Respect **CODEOWNERS** and branch policy (**feature/fix -> `development`**, release PRs **`development` -> `master`**) described in [dev-workflow](../dev-workflow/SKILL.md)
 
 ## References
 

skills/dev-workflow/SKILL.md

@@ -32,12 +32,12 @@ description: Use when setting up the dev environment, running build/test/docs, o
 
 ### Branches and PRs
 
-- `.github/workflows/check-branch.yml` blocks merging into **`master`** unless the head branch is **`staging`** (organizational policy). Prefer PRs that follow team conventions for `master` / `staging`.
+- Feature/fix PRs should target **`development`**. Release PRs are raised directly from **`development`** to **`master`**.
 - Use `CODEOWNERS` for required reviewers when applicable
 
 ### CI and automation (no RSpec workflow today)
 
-- **Release:** `.github/workflows/release-gem.yml` — on GitHub **release created**, builds and pushes to RubyGems (note: workflow pins Ruby 2.7 for publish; align with gemspec minimum when changing)
+- **Release:** `.github/workflows/release-gem.yml` — on GitHub **Release** created (`release: types: [created]`) for tag **`v*`** (draft releases skipped), checks out the tag, then builds and pushes to RubyGems (note: workflow pins Ruby 2.7 for publish; align with gemspec minimum when changing)
 - **Security / compliance:** CodeQL, policy scan, SCA scan — see `.github/workflows/`
 - **Issues:** Jira integration workflow in `.github/workflows/issues-jira.yml`
 

skills/framework/SKILL.md

@@ -35,7 +35,7 @@ description: Use when changing the gemspec, Bundler setup, Ruby/runtime constrai
 ### Build and publish
 
 - Local artifact: `gem build contentstack_utils.gemspec`
-- Publishing is triggered by GitHub **release** per `release-gem.yml`
+- Publishing runs when a GitHub **Release** is created (`release: types: [created]`) for tag **`v*`** (draft releases skipped); see `release-gem.yml`.
 
 ## References