Skip to main content

External repositories

Infrahub supports two different types of connections to external Git repositories:

  • CoreRepository fully integrates with Git version control, including branch tracking and two-way branch synchronization.
  • Read-only Repository links a particular branch in Infrahub to a particular ref in the Git repository. It will only read from the Git repository. It will never make any changes to the external repository.

GitHub personal access token​

Generate a GitHub fine-grained personal access token
  1. Go to settings > Developer Settings > Personal access tokens New GitHub token
  2. Select Fine-grained tokens
  3. Limit the scope of the token in Repository Access > Only Select Repositories
  4. Grant the token permission:
  • a. If you want to create a CoreRepository using this token, then you will need to give it Read/Write access for the Content of the repository.
  • b. If you want to create a Read-only Repository using this token, then you will only need to give it Read access for the Content of the repository.

Fine-Grained Token

Adding a repository​

You will need to submit an access token with your request to create a repository in Infrahub. Infrahub uses your username and this token to connect to the external Git repository.

Via the web interface​

Add a Git Repository

  1. Log in to the Infrahub UI
  2. Go to Unified Storage > Repository or Read-only Repository
  3. Click on the + plus sign
  4. Complete the required information:

The name you want to give the repository in Infrahub for identification purposes.

Validate that everything is correct

In the UI, you should see your new repository. Click on the row for the repository to see more detailed information. If the repository you added doesn't have the Commit property populated it means that the initial sync didn't work. Verify the location and credentials.

Via the GraphQL interface​

Using the GraphQL Interface, it is possible to add a CoreRepository or Read-only Repository via a Mutation.

info

If you are using GitHub as your Git Server, you need to have a fine-grained personal access token to be able to access the repository.

  1. Open the GraphQL Interface.
  2. Add your authentication token with the Headers
  3. Copy-paste the correct mutation from below and complete the information
  # Endpoint: http://127.0.0.1:8000/graphql/main
  mutation {
    CoreRepositoryCreate(
      data: {
        name: { value: "YOUR_REPOSITORY_NAME" }
        location: { value: "https://GIT_SERVER/YOUR_GIT_USERNAME/YOUR_REPOSITORY_NAME.git" }
        username: { value: "YOUR_GIT_USERNAME" }
        password: { value: "YOUR_PERSONAL_ACCESS_TOKEN" }
        # default_branch: { value: "main" } <-- optional
      }
    ) {
      ok
      object {
        id
      }
    }
  }
Validate that everything is correct

In the UI, new objects that have been imported from the Git Repository should now be available:

The repository should be visible under Unified Storage / Repository or Unified Storage / Read-only Repository depending on which type of repository you created. If the repository you added doesn't have the commit property populated, then it means that the initial sync didn't work. Verify the location and credentials.

Updates from the external repository​

Read-only repositories and CoreRepositories work in different ways when it comes to tracking changes on the remote repository.

CoreRepository​

The Infrahub Git agent checks for changes in external repositories several times per minute. If there are no conflicts between the remote and the Infrahub branches, the Git agent will automatically pull any new changes into the appropriate Infrahub branch.

Read-only Repository​

Infrahub does not automatically update Read-only Repositories with changes on the external repository. To pull in changes from the external repository you must either set the ref and/or commit of the Read-only Repository to the desired value. You can perform this update either through the user interface or via an update mutation through the GraphQL API. Either way, the Infrahub web server will use the Git agent to retrieve the appropriate changes in a background task.

Example update mutation
  # Endpoint : http://127.0.0.1:8000/graphql/main
  mutation {
    CoreReadOnlyRepositoryUpdate(
      data: {
        id: "ID_OF_THE_REPOSITORY"
        ref: { value: "BRANCH/TAG/COMMIT TO TRACK" }
        commit: { value: "NEW COMMIT ON THE REF TO PULL" }
      }
    ) {
      ok
      object {
        id
      }
    }
  }

Updates to the external repository​

CoreRepository​

When a Proposed Change is merged, if the source and destination Infrahub branches are both linked to branches on the same external Git repository, then Infrahub will handle merging the branches on the external Git repository. This is the only time that Infrahub will push changes to the external repository. Other changes made within Infrahub will not be pushed to an external repository and could potentially be overwritten when Infrahub pulls new commits from the external repository.

Read-only Repository​

No changes to objects owned by a Read-only Repository are ever pushed to the external Git repository.