Skip to main content

Pilot Participant Guide

This guide is for GRID Pilot Participants. It explains the set up for participants based on the Pilot Design (see Pilot Design Document).

It is a good idea to read the design document first to understand the context for these instructions.

1. Overview​

You are setting up a Sovereign Node. This is a standard GitLab repository that you control. We will "harvest" the data you make available about the Registries you choose to publish, we will check it against the signature you tell us you will use, and we will display the verified results in the Global Registrar Information Directory.

This means that we cannot modify your data.

2. Requirements​

  1. GPG Key: You must generate a GPG Keypair (RSA 4096) to act as your Digital Identity.

  2. GitLab Repo: A private repository on GitLab.com.

  3. Deploy Token: A read-only token so our Harvester can see your repo.

3. Setup Instructions​

Step 1: Identity & Config​

  1. Generate your GPG Key and upload the Public Key to your GitLab User Settings.

  2. Configure your local Git to sign commits automatically:

    Bash

    git config --global user.signingkey <YOUR_KEY_ID>
    git config --global commit.gpgsign true

Step 2: Repository Structure​

Your repository represents your Country. You may host multiple registrars inside it. Create the following folder structure:

Plaintext

/ (Root)
├── did.json                  <-- Your Identity Document
└── registrars/               <-- Folder for your data
    ├── companies-house.md    <-- Registrar #1
    └── land-registry.md      <-- Registrar #2

Step 3: Creating Registrar Entries​

For each registrar, create a markdown file in the registrars/ folder. Important: Ensure the country_code is your correct ISO 3-letter code.

Template (registrars/companies.md):

YAML

---
country_code: "GBR"
registrar_name: "Companies House"
did: "did:web:gtr-pilots.gitlab.io:uk-pilot"  # Points to your Repo Root
status: "active"
signing_key_id: "3AA5C343"                    # Your Key ID
contacts:
  - role: "admin"
    email: "admin@companieshouse.gov.uk"
---

# Authority Statement
This registry operates under the Companies Act 2006...

Note that the signing_key_id value must be the "fingerprint" value of the public key. You can use this command to find the string:

gpg --list-secret-keys --keyid-format LONG

The output will look something like this, where the fingerprint is the long string of numbers and letters on the second line:

sec   rsa4096/3AA5C34371567BD2 2024-03-01 [SC]
      F296BDE50FC2E9348271031C3AA5C34371567BD2   <-- COPY THIS
uid                 [ultimate] UK Pilot Admin <admin@pilot.gov>

Update your registrar.md file with that full string:

registrar_name: "UK Companies House"
signing_key_id: "F296BDE50FC2E9348271031C3AA5C34371567BD2"

Step 4: Hosting your DID (Identity)​

For the pilot we are currently using the did:web standard. This means that you must publish your pilot did.json file to the web.

  1. Place did.json in your repository root.

  2. Add a .gitlab-ci.yml file to publish it:

    YAML

    pages:
     stage: deploy
     script:
       - mkdir public
       - cp did.json public/
     artifacts:
       paths:
         - public
     only:
       - main

  3. CRITICAL: Go to Settings > Pages and uncheck "Use unique domain".

  4. Your DID will be something like: did:web:gtr-pilots.gitlab.io:genovia, where gtr-pilots.gitlab.io:genovia is replaced by your pages URL and project name.

Step 5: Connection​

To go live, send the following to the UN/CEFACT Pilot Lead via secure channel:

  1. Repository URL (e.g., https://gitlab.com/gtr-pilots/uk-pilot.git)

  2. Deploy Token Username & Password (Scope: read_repository)

  3. Your Public GPG Key (The .asc file)

Once received, we will add you to the Harvester. Within 6 hours, your registrars will appear in the Global Directory with a Verified Trust Badge.