How do I register a source?

A source is where your target state definitions live: a Git repository on GitLab, GitHub or Azure DevOps, or a folder in LUSID Drive.

Registering a new source takes a few minutes, and from then on every definition stored there is versioned, listed under Target State Definitions, and ready to deploy.

Prerequisites

• Admin Portal access with the entitlement to create definition sources. If you can see Sources under Data Management but the Add source button is missing, you have read-only access. Ask your administrator for write access.

• For a Git source:

  • An existing repository on GitLab, GitHub or Azure DevOps, with the branch you want to use already created. Admin Portal never creates branches.

  • Permission on the provider side to create a personal access token for that repository.

  • The repository must be reachable over https from the internet. Self-hosted GitLab, GitHub Enterprise Server and Azure DevOps Server are supported, but a host on a private network must first be allowed by FINBOURNE. Contact your FINBOURNE representative before registering one.

• For a LUSID Drive source: a folder in Drive that you can read and write.

Methods

Choose the method that matches where your definitions will live. If you are unsure, a LUSID Drive folder is the quickest to set up because it needs no repository access and no token. A Git repository keeps definitions versioned and reviewable alongside your other code.

Method 1: Register a GitLab repository

Step 1: Create a GitLab token

Admin Portal reads definitions from the repository and commits changes back, so the token needs read and write access.

1. In GitLab, select your avatar, then Preferences > Access > Personal access tokens.

2. From the Generate token dropdown choose Fine-grained token, then give it a name and an expiry you are willing to rotate.

3. Under Group and project access, limit the token to the group or project holding your definitions. Do not grant anything wider.

4. Under Add resource permissions grant exactly these permissions and nothing else:

   • Project: Read

   • Repository: Read, Create and Update

   • Commit: Read

5. Generate the token and copy it.

Note: The Project: Read permission is required by the connection test. Without it GitLab hides the project from the token entirely, and Admin Portal reports that the repository cannot be found.

Step 2: Add the source in Admin Portal

1. Navigate to Data Management > Sources and select Add source.

2. Under Where will these definitions live? select Source control.

3. Under Name this source, enter a Display name. It must be unique among your sources. Optionally add a Description.

4. Under Connect the repository:

   • Provider: leave as GitLab.

   • Repository: enter the project path, such as group/project or group/subgroup/project, or paste the full https://gitlab.com/... URL. For self-hosted GitLab, paste the full URL so Admin Portal knows the host.

   • Branch: the branch to read from and commit to. Leave blank to use main.

   • Path (optional): the folder inside the repository that holds your definitions, such as config/target-states. Leave blank to use the repository root.

   • Access token: paste the token from Step 1.

5. Select Test connection. A successful test returns: Connection verified — the token can read this repository. Write access is exercised the first time a definition is saved to this source.

6. Select Add source.

Method 2: Register a GitHub repository

Step 1: Create a GitHub token

1. In GitHub, open Settings > Developer settings > Personal access tokens > Fine-grained tokens, then Generate new token.

2. Set Resource owner to the account or organisation that owns the repository, and an Expiration you are willing to rotate.

3. Under Repository access choose Only select repositories, and pick just the repositories holding your definitions.

4. Under Permissions > Repository permissions grant Contents: Read and write, and leave Metadata: Read in place. The connection test reads repository metadata. Nothing else is needed.

5. Generate the token and copy it.

Step 2: Add the source in Admin Portal

Follow the steps in Method 1, Step 2, with these differences:

• Set Provider to GitHub.

• In Repository, enter owner/repository or paste the full https://github.com/... URL. For GitHub Enterprise Server, paste the full URL.

Method 3: Register an Azure DevOps repository

Step 1: Create an Azure DevOps token

1. In Azure DevOps, open User settings (the icon beside your avatar), then Personal access tokens, then New Token.

2. Set Organization to the organisation holding your repository, and an Expiration you are willing to rotate. A token is scoped to one organisation and cannot see any other, however valid it is.

3. Under Scopes choose Custom defined, then tick Code: Read & write. Nothing else.

4. Create the token and copy it while it is still shown.

Step 2: Add the source in Admin Portal

Follow the steps in Method 1, Step 2, with these differences:

• Set Provider to Azure DevOps.

• In Repository, enter organisation/project/repository, or paste the full URL such as https://dev.azure.com/organisation/project/_git/repository. URLs in the https://organisation.visualstudio.com/... form are also accepted.

Method 4: Register a LUSID Drive folder

A Drive source needs no token. Admin Portal reads and writes the folder using your own LUSID access.

1. Navigate to Data Management > Sources and select Add source.

2. Under Where will these definitions live? select LUSID Drive location.

3. Under Name this source, enter a Display name and, optionally, a Description. Admin Portal suggests a name based on the folder until you type your own.

4. Under Choose the LUSID Drive folder, either:

   • use the Browse LUSID Drive tab to navigate to the folder and select Use this folder. You can create a new folder here with New folder; or

   • use the Enter path tab and type the folder path, such as /config/target-states. You can also paste a link to a Drive folder and Admin Portal resolves it to a path.

5. Select Add source.

Every .json file in the folder is scanned as a candidate definition. Other files are ignored.

After you add a source

The source appears in the list on the Sources page with a Connected status. Its row shows the provider, branch, path and how many definitions were found. From the row's menu you can:

• Test connection: re-check that the stored token can still read the repository. Not shown for Drive sources, which have nothing to check.

• Upload Target State Definition: save a definition file from your computer into this source. Only available while the source is Connected.

• Edit source: rename the source, change its description, or paste a new access token. The provider, repository, branch and path are fixed once created. To point at a different location, add a new source.

• Remove source: unregister the source. This hides its definitions from Admin Portal but never changes a domain and never deletes anything from the repository or folder.

Once your source is connected, you can create a target state definition for it.

Rotating a token

Tokens expire on the date you chose when you created them. Admin Portal does not track expiry, so plan your own reminder. When a token expires, the source shows Needs attention after the next connection test, and reads and saves against it fail until you rotate it.

To rotate:

1. Create a new token on the provider, following Step 1 of the relevant method above.

2. On the Sources page, open the row menu and select Edit source.

3. Under Access token, paste the new token. Leave the field blank to keep the current token.

4. Optionally select Test connection, then select Save changes.

Admin Portal verifies the new token against the repository before it replaces the stored one. The following table summarises token permissions:

Troubleshooting

The provider rejected the token. The message names the exact permissions the token needs. Check the token has not expired and that it grants everything listed, then try again. On GitLab, a token with Repository: Read but without Create and Update passes the connection test and then fails the first time you save a definition.

Either this repository does not exist, or the token cannot see it. Providers answer the same way in both cases. Check the repository path or URL character by character. Then check the token's repository access:

• GitLab: the token must grant Project: Read. A fine-grained token without it is refused even when its Repository permissions are correct.

• GitHub: the repository must be listed under the token's Repository access.

• Azure DevOps: the token must have been created in the same organisation as the repository.

The provider could not be reached. Check the repository URL. If the host is on a private network or behind a firewall, it must be allowed by FINBOURNE before Admin Portal can reach it. Contact your FINBOURNE representative.

The repository URL must use HTTPS. Admin Portal sends the access token with every request, so it refuses http URLs and never follows redirects. Use the https URL for the repository.

That display name is already used by another source. Source names must be unique, ignoring case. Choose a different name.

A source shows Needs attention. Select Test connection on the row. The message beneath the row explains what failed. Most often the token has expired or lost a permission, in which case rotate it as described above.

FAQs

Where is my access token stored? In your domain's LUSID Configuration Store as a secret, not in the Admin Portal database. It is never shown again, never returned by any API, and never written to logs. Only you can reveal what you have just typed in the token field, before saving.

Can I use a classic GitHub token or a GitLab deploy token? The guided setup assumes fine-grained personal access tokens. See the questions below.

Can I point two sources at the same repository? Yes, for example at different branches or folders. Each source needs its own display name.

What happens to my definitions if I remove a source? The files in your repository or Drive folder are untouched. Admin Portal stops listing them, and any deployment that read its definition from that source asks you to choose a new origin the next time you redeploy it.

Does Admin Portal open merge requests or pull requests? No. Saving a definition commits straight to the branch you configured, with a commit message such as Update target state definition default/eod-holdings via Admin Portal. If you want review before changes land, point the source at a working branch and merge to your main branch using your normal process.