--- title: "How do I register a source for target state definitions?" slug: "how-do-i-set-up-a-source-in-admin-portal" updated: 2026-10-16T10:35:27Z published: 2026-10-16T10:35:27Z canonical: "support.lusid.com/how-do-i-set-up-a-source-in-admin-portal" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.lusid.com/llms.txt > Use this file to discover all available pages before exploring further. # How do I register a source for target state definitions? A *source* is where your [target state definitions](/v1/docs/how-do-i-create-a-target-state-definition-in-admin-portal) 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. ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-CV40QYJE.png?sv=2026-02-06&spr=https&st=2026-11-09T06%3A50%3A29Z&se=2026-11-09T07%3A50%3A29Z&sr=c&sp=r&sig=JgU7sfCFKQ7enlqj6OxKT1BMaR%2BOaQtUo4%2B%2F45GsRd0%3D) ## Prerequisites - Admin Portal access with the entitlement to create definition sources. If you can see **Sources** under **Configuration 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] > **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. **Other token types**: A legacy personal access token, or a project or group access token, also works if it has the `api` scope and a role that can push to the branch. `read_api` is not enough, because Admin Portal commits changes back. A deploy token does not work, because GitLab does not accept deploy tokens on its API. #### Step 2: Add the source in Admin Portal 1. Navigate to **Configuration 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. **Other token types**: A classic personal access token also works if it has the `repo` scope. `public_repo` is enough when the repository is public. #### 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 **Configuration 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](/v1/docs/how-do-i-create-a-target-state-definition-in-admin-portal) 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: | Source | Token type | Permissions | | --- | --- | --- | | GitLab | Fine-grained personal access token | Project: Read Repository: Read, Create and Update Commit: Read | | Legacy personal access token, or project or group access token (GitLab deploy tokens are not supported). | `api` scope, with a role that can push to the branch | | GitHub | Fine-grained personal access token | Contents: Read and write Metadata: Read | | Classic personal access token | `repo` scope (`public_repo` for a public repository) | | Azure DevOps | Personal access token, custom defined scopes | Code: Read & write | ## 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?** A classic GitHub personal access token works if it has the `repo` scope, or `public_repo` for a public repository. A GitLab deploy token does not work, because GitLab does not accept deploy tokens on its API. GitLab legacy personal access tokens, and project or group access tokens, work with the `api` scope. The **Add source** dialog lists these under **Other token types**. **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.