How to Integrate Lovable with Mercurial

Before writing any code, you need to securely store your Heptapod or Bitbucket credentials. Never paste API tokens into Lovable's chat or directly into your code — on the free tier, chat history is publicly visible, and tokens embedded in code end up in your Git history where they can be recovered. To add your credentials: open your Lovable project, click the Cloud tab (the icon that looks like a database or cluster, found by clicking the '+' panel button in the top area of the editor). Inside the Cloud tab, locate the Secrets section. Click 'Add Secret'. For Heptapod, create a secret named HEPTAPOD_TOKEN and paste your Personal Access Token as the value. Also add HEPTAPOD_BASE_URL with the value set to your Heptapod instance URL (e.g., https://foss.heptapod.net). If you are using Bitbucket with an App Password, create secrets named BITBUCKET_USERNAME and BITBUCKET_APP_PASSWORD. Lovable encrypts these values immediately upon saving. They will only be accessible from Edge Functions via Deno.env.get() — never from client-side React code. If you see a 'Secret [NAME] not found' error later, the most common cause is a typo between the secret name you stored and the name you reference in code, so double-check for exact case matching.

Now you'll create the Edge Function that acts as your Hg-to-Lovable bridge. This function will receive requests from your Lovable frontend, authenticate with the Heptapod API using your stored credentials, and return changeset data in a format your React components can consume. In Lovable's chat, describe what you want and the AI will generate and deploy the Edge Function automatically. The function is written in TypeScript and runs on the Deno runtime, so it uses Deno.env.get() for secrets and native fetch for HTTP requests. It lives at supabase/functions/hg-proxy/index.ts in your project's file structure. The function should handle CORS so your frontend can call it from the browser, validate that requests come from your own app (not arbitrary external callers), and proxy the Heptapod REST API endpoint for listing changesets. Heptapod's API follows GitLab's REST conventions — for example, GET /api/v4/projects/:id/repository/commits returns commit (changeset) data. You'll pass your project path URL-encoded as the project ID parameter.

1import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
2
3const corsHeaders = {
4  'Access-Control-Allow-Origin': '*',
5  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
6}
7
8serve(async (req) => {
9  if (req.method === 'OPTIONS') {
10    return new Response('ok', { headers: corsHeaders })
11  }
12
13  try {
14    const heptapodToken = Deno.env.get('HEPTAPOD_TOKEN')
15    const heptapodBaseUrl = Deno.env.get('HEPTAPOD_BASE_URL')
16
17    if (!heptapodToken || !heptapodBaseUrl) {
18      return new Response(
19        JSON.stringify({ error: 'Missing Heptapod credentials in Secrets' }),
20        { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
21      )
22    }
23
24    const url = new URL(req.url)
25    const endpoint = url.searchParams.get('endpoint')
26
27    if (!endpoint) {
28      return new Response(
29        JSON.stringify({ error: 'Missing endpoint query parameter' }),
30        { status: 400, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
31      )
32    }
33
34    // Only allow read-only API paths
35    const allowedPrefixes = ['projects/', 'groups/']
36    const isAllowed = allowedPrefixes.some(prefix => endpoint.startsWith(prefix))
37    if (!isAllowed) {
38      return new Response(
39        JSON.stringify({ error: 'Endpoint not permitted' }),
40        { status: 403, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
41      )
42    }
43
44    const apiUrl = `${heptapodBaseUrl}/api/v4/${endpoint}`
45    const response = await fetch(apiUrl, {
46      headers: {
47        'Authorization': `Bearer ${heptapodToken}`,
48        'Content-Type': 'application/json',
49      },
50    })
51
52    const data = await response.json()
53
54    return new Response(
55      JSON.stringify(data),
56      {
57        status: response.status,
58        headers: { ...corsHeaders, 'Content-Type': 'application/json' },
59      }
60    )
61  } catch (error) {
62    return new Response(
63      JSON.stringify({ error: error.message }),
64      { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
65    )
66  }
67})

With the Edge Function deployed, you can now build the React component that calls it and renders Mercurial changeset data. The component will call your hg-proxy Edge Function with the appropriate Heptapod API path for your repository's commits endpoint. In Heptapod's GitLab-compatible API, the path follows the pattern projects/:encoded_project_path/repository/commits where the project path is URL-encoded (forward slashes become %2F). For example, if your Heptapod project path is my-org/my-repo, you'd call: /functions/v1/hg-proxy?endpoint=projects%2Fmy-org%2Fmy-repo%2Frepository%2Fcommits&per_page=20 The Lovable AI can generate this component for you if you describe the data shape you want to display. Be specific about which fields from the changeset you want to show: the short hash (the first 8 characters of the full SHA), the author name and email, the commit message, and the timestamp. Heptapod returns commits in GitLab format with fields like id (full hash), short_id, author_name, authored_date, and message. You'll use the Supabase client's functions.invoke() method to call the Edge Function, or a standard fetch() to the function URL. The supabase.functions.invoke() approach is slightly cleaner as it automatically includes the required apikey header.

Mercurial repositories on Heptapod can have thousands of changesets across dozens of named branches. Returning all of them at once would be slow and wasteful. The Heptapod API supports cursor-based pagination via the page and per_page query parameters, and you can filter by branch (ref_name in the commits endpoint) to show only changesets from a specific named branch or bookmark. Update your Edge Function or your frontend call to support a branch parameter. When the user selects a branch from a dropdown, your component rebuilds the endpoint string to include ref_name=<branch_name>. For example: projects%2Fmy-org%2Fmy-repo%2Frepository%2Fcommits?ref_name=default&per_page=20&page=2 — where default is Mercurial's default branch name (equivalent to Git's main). For pagination, Heptapod returns X-Next-Page and X-Total-Pages headers in the response. Your Edge Function currently returns only the JSON body — update it to also forward these headers so the frontend knows whether to show a 'Load more' button. Alternatively, you can store fetched changesets in a Supabase table and build pagination against that local cache, which reduces live API calls and makes the UI feel faster. For complex cases, RapidDev's team can help configure a scheduled Edge Function that syncs Mercurial changeset data into a Supabase table on a regular interval, giving you fast query performance without hitting the Heptapod API on every page load.

Before considering this integration production-ready, run through a security and correctness checklist. First, verify that your Edge Function is not publicly callable with arbitrary Heptapod endpoints — the allowedPrefixes check in the code should block attempts to call admin or write endpoints. Test this by calling the function URL directly with an endpoint like users/admin and confirming it returns a 403 status. Second, verify your secrets are properly isolated. Open your browser's developer tools on the deployed Lovable app and inspect the network requests. You should see calls to your Edge Function URL (/functions/v1/hg-proxy), but the Heptapod token should never appear in any request from the browser — it should only appear in the server-side Edge Function logs, which you can view in Cloud → Logs. Third, check Cloud → Logs to confirm the Edge Function is running without errors. Each invocation appears as a log entry. If you see 'Missing Heptapod credentials in Secrets', the secret names in your code do not exactly match the names you stored in the Secrets panel — this is a case-sensitive comparison, so HEPTAPOD_TOKEN and heptapod_token are treated as different names. Finally, test the component in Lovable's preview with your actual repository path. If the changeset list renders correctly, your Hg-to-Lovable bridge is working. Note that Lovable's preview runs inside an iframe, and some CORS configurations may behave differently in preview versus the deployed app — test on the published URL if you see unexpected CORS errors in preview.