Skip to main content

2 posts tagged with "environments"

View All Tags

Github: Show deployed service URLs

Open staging and production URLs for this service instantly
🔒
https://github.com/mycompany/webshop
preload

How does this help you?​

  • Quickly access the staging and production URLs for repositories

Preview​

How it looks in the extension

ToolJump•
Deployed URLs
• ... Other items ...

High level approach​

There are two common ways to map a repository to its deployed URLs:

  1. Data file (simple): Keep a small mapping file alongside your integrations that lists, for each repo, the staging and production URLs. This is easy to start with and version‑controlled.
  2. Service catalog (scalable): Query your source of truth (e.g., Backstage, Datadog Service Catalog) to resolve environment endpoints dynamically. This is preferable when you already maintain a catalog.

Below, we implement approach number 1 (the simple data file approach) and render a dropdown with links to staging and production.

Example data file (deployed-urls.data.json)​

{
  "mappings": {
    "company/webshop": {
      "production": "https://webshop.company.com",
      "staging": "https://staging.webshop.company.com"
    },
    "company/notifier": {
      "production": "https://notifier.company.com",
      "staging": "https://staging.notifier.company.com"
    }
  }
}

Prerequisites​

No external auth required. Add the data file (e.g., deployed-urls.data.json) to your data directory in your Github repository. Learn more about data files in Data.

Code​

github.deployed-urls.integration.example.js
module.exports = {
    metadata: {
        name: 'github-show-deployed-service-urls',
        description: 'Show staging and production URLs for this repository as a dropdown, using a data file mapping',
        match: {
            contextType: 'github',
            context: {
                'page.repository': { startsWith: 'my-org/' }
            }
        },
        requiredSecrets: [],
        cache: 300
    },
    run: async function (context, secrets = {}, dataFiles = []) {
        const repo = context.page.repository; // e.g., "company/webshop"

        // Expect a data file like deployed-urls.data.json with shape:
        // { "mappings": { "org/repo": { "production": "https://...", "staging": "https://..." } } }
        const df = dataFiles.find(f => f.id === 'deployed-urls');
        if (!df || !df.data) {
            return [];
        }

        const mappings = df.data.mappings || {};
        const envs = mappings[repo];
        if (!envs || (typeof envs !== 'object')) {
            return [];
        }

        const items = [];
        if (envs.production) {
            items.push({ content: 'Production', href: envs.production, status: 'important', icon: 'link' });
        }
        if (envs.staging) {
            items.push({ content: 'Staging', href: envs.staging, icon: 'link' });
        }

        if (items.length === 0) {
            return [];
        }

        return [
            {
                type: 'dropdown',
                content: 'Deployed URLs',
                items
            }
        ];
    }
};

GitHub → CircleCI: Browse deployment

How does this help you?​

  • One-click to browse the exact Git commit deployed to each environment
  • Reduces guesswork when debugging differences between environments

Preview​

How it looks in the extension

ToolJump•• ... Other items ...

Approaches​

  • Insights by workflow name (implemented): Use CircleCI Insights for conventional workflow names (e.g., deploy-staging, deploy-prod) on branch main, find the latest successful run, resolve the pipeline to get the commit SHA, and link to the GitHub tree. Simple and widely applicable.
  • Pipelines + workflows traversal: List recent pipelines for the repo/branch, then fetch workflows per pipeline to find the most recent successful deploy job per environment. More API calls, similar outcome.
  • Artifact or metadata lookup: Emit an artifact or store metadata (e.g., commit SHA, release tag, URL) during deploy jobs and fetch it via the Artifacts API. More setup, flexible if your org already publishes metadata.

Assumptions​

  • Branch: main. Adjust in the example if your default deploy branch differs.
  • Workflows: deploy-staging and deploy-prod. Rename to match your pipeline.
  • Output: a dropdown labeled Browse deployment with Staging and Prod items linking to https://github.com/<org>/<repo>/tree/<sha>.

Prerequisites​

For the code below to work, please follow the guide on Connecting to CircleCI. Provide CIRCLECI_API_TOKEN as a secret.

Code​

github.circleci.browse.deployment.integration.example.js
module.exports = {
    metadata: {
        name: 'github-circleci-browse-deployment',
        description: 'Dropdown to browse the deployed revisions (staging, QA) on GitHub using CircleCI workflows',
        match: {
            contextType: 'github',
            context: {
                'page.repository': { startsWith: 'my-org/' }
            }
        },
        requiredSecrets: ['CIRCLECI_API_TOKEN'],
        cache: 300
    },
    run: async function (context, secrets = {}) {
        const CIRCLE_HOST = 'https://circleci.com/api/v2';
        const repo = context.page.repository; // e.g., "org/repo"
        const projectSlug = `gh/${repo}`;
        const branch = 'main';

        // Conventional workflow names used by many teams; customize if needed
        const WORKFLOWS = {
            staging: 'deploy-staging',
            prod: 'deploy-prod'
        };

        const headers = {
            'Circle-Token': secrets.CIRCLECI_API_TOKEN,
            'Accept': 'application/json'
        };

        async function getDeployedShaForWorkflow(workflowName) {
            // Use Insights to find the most recent successful run for the workflow on the target branch
            const insightsUrl = `${CIRCLE_HOST}/insights/${encodeURIComponent(projectSlug)}/workflows/${encodeURIComponent(workflowName)}?branch=${encodeURIComponent(branch)}`;
            const r1 = await fetch(insightsUrl, { headers });
            if (!r1.ok) throw new Error(`CircleCI insights error (${workflowName}): ${r1.status} ${r1.statusText}`);
            const j1 = await r1.json();
            const items = Array.isArray(j1.items) ? j1.items : [];
            const success = items.find(i => i.status === 'success');
            if (!success) return null;

            // Resolve pipeline id from pipeline number so we can get VCS revision (commit SHA)
            const byNumberUrl = `${CIRCLE_HOST}/project/${encodeURIComponent(projectSlug)}/pipeline/${success.pipeline_number}`;
            const r2 = await fetch(byNumberUrl, { headers });
            if (!r2.ok) throw new Error(`CircleCI pipeline lookup error: ${r2.status} ${r2.statusText}`);
            const j2 = await r2.json();
            const pipelineId = j2.id;
            if (!pipelineId) return null;

            const pipelineUrl = `${CIRCLE_HOST}/pipeline/${pipelineId}`;
            const r3 = await fetch(pipelineUrl, { headers });
            if (!r3.ok) throw new Error(`CircleCI pipeline fetch error: ${r3.status} ${r3.statusText}`);
            const j3 = await r3.json();
            const sha = j3.vcs && j3.vcs.revision;
            return sha || null;
        }

        const [stagingSha, prodSha] = await Promise.all([
            getDeployedShaForWorkflow(WORKFLOWS.staging),
            getDeployedShaForWorkflow(WORKFLOWS.prod)
        ]);

        const items = [];
        if (stagingSha) {
            items.push({ content: 'Staging', href: `https://github.com/${repo}/tree/${stagingSha}` });
        }
        if (prodSha) {
            items.push({ content: 'Prod', href: `https://github.com/${repo}/tree/${prodSha}` });
        }

        if (items.length === 0) return [];

        return [{
            type: 'dropdown',
            content: 'Browse deployment',
            icon: 'github',
            items
        }];
    }
};