Integration with an External VCS

Overview

Every lab uses Instruqt’s native version control from the moment you create it. No setup is required: each time you Publish a lab, the commit shows up in Change History.

You can also connect a lab to a repository on GitHub, so publishing keeps that repository in sync alongside the native history. Disconnecting stops the syncing but keeps everything you already have, both in Instruqt and in the repository.

Setting up the GitHub integration

Before any lab can be connected to a repository, your Instruqt organization needs a GitHub account integration. This is a one-time setup per GitHub account, managed under Integrations → Version control in the management interface (/manage/<organization>/version-control):

• Add GitHub account installs the Instruqt GitHub App on a GitHub organization or user account and lets you choose which repositories it can access.
• Configure on GitHub, next to each account you added, opens the app’s settings on GitHub. There you change which repositories the app can access. Use it to grant access to a repository you created after the initial setup.

If a repository doesn’t show up when you import or connect a lab, the GitHub App has no access to it. Click Configure on GitHub for the account and grant access to that repository.

Importing a lab from a repository

If a repository already contains lab code, import it. Don’t connect it to an existing lab.

1. On the Labs page, click Import lab in the top right. The Import lab from a Git repository dialog opens.
2. Select the Git account from the dropdown.
3. Find the repository and click Select. Private repositories show a lock icon. If the repository isn’t listed, grant the GitHub App access to it first (see Setting up the GitHub integration).
4. Review the import settings:
   • Lab name is prefilled from the repository name.
   • Branch is the branch to sync with. It defaults to the repository’s default branch.
   • Root directory is the directory that contains the lab’s HCL files. Use it when the lab is in a subdirectory of a shared repository.
5. Click Import lab.

Instruqt creates the lab from the repository and keeps the two connected, so later pushes sync to the lab.

Connecting a lab

Connecting is the reverse of importing. It links a lab that already exists on Instruqt to a repository, usually an empty one that will receive the lab’s content.

Connecting to a repository that already has content

Connect fetches the repository before it pushes. If the lab’s history can fast-forward onto what is there, its branches are pushed without force. If the repository holds a history the lab shares nothing with, the connect is refused, and the dialog asks which side to keep: the lab’s content overwrites the repository, or the repository’s content replaces the lab’s.

To bring a repository that already contains a lab into Instruqt, import it instead. Importing keeps one history for both sides; connecting always ends with one side overwriting the other.

Open the lab and click Project settings in the top bar, then select Version control in the settings sidebar.

If the lab isn’t connected yet, the page shows a Connect repository button. The same button appears as a Connect your repository card in the Change history section of the lab’s Overview page while no repository is connected.

Clicking Connect repository opens the Connect repository dialog:

1. Pick the GitHub account to use from the Git account dropdown. If no account is listed, click Configure GitHub App to install or grant the Instruqt GitHub App access to your organization (this is the same setup described in Setting up the GitHub integration). This opens GitHub in a new tab, and the dialog refreshes automatically once you switch back.
2. Search for the repository you want, or scroll the list. Private repositories show a lock icon next to their name. If the repository isn’t listed, the GitHub App doesn’t have access to it yet - use Configure on GitHub for the account (see above) and grant access to that repository.
3. Click Connect next to the repository you want to use.
4. If the repository holds content that did not come from this lab, the dialog does not connect yet: it asks which content to keep. Choose Keep the lab’s content to overwrite the repository, or Keep the repository’s content to replace the lab’s content with what the repository holds, then click Connect and overwrite. An empty repository, or one the lab’s history can fast-forward onto, connects without this step.

A success notification confirms the connection. The Version control page then shows the connection’s details: Account, Repository (a link to the repository on GitHub), Default branch, and Directory.

The notification confirms that the lab is linked, not that the first push succeeded. Open the repository on GitHub and check that the lab’s files are there.

Disconnecting a lab

On the Version control settings page, click Disconnect. A confirmation dialog titled “Disconnect from your version control system” explains what happens: the lab stops syncing with the connected repository, a copy of the content remains in your VCS, and the lab’s versions, change history, and other version control abilities stay available through the native Instruqt version control. Confirm by clicking Disconnect again.

Only a lab connected at its repository’s root directory (/) can be disconnected. If it was connected at a sub-directory, the Disconnect button is disabled because the connection is shared with other labs rooted in that same repository. See Limitations for details.

Learn more

• Editing & Publishing covers how edit mode, Add changes, and Publish work, whether or not a lab is connected to an external repository.
• Version Control overview covers what version control means across the platform and its current limitations.