7 minute read

Creating Repos for Nautobot Use

In Part 1 we discussed creating repositories for automation in general, such as for code you’ve written that you want to share with the public, or bugfixes you want to contribute to existing packages. But many SOT platforms also require the use of a remote git repository to store and track changes to various kinds of text data that support automation applications.

For Nautobot specifically, such as for the Golden Config plugin or Config Contexts, you will need to create repositories remotely (let’s assume GitHub for simplicity) and then set them up as a data source under the Extensibility menu (tested on version 1.5.9). Let’s take the example of backing up configurations in GC.

Create a New Repo

  1. In GitHub, navigate to the Repositories tab under your organization and click the green “New repository” button.
  2. Enter a repository name such as “gc-backups” and a description, select “Private” if it’s owned by your organization (generally we don’t want to expose our config backups to the public eye), then check “Add a README file” if you like (in this case, it’ll be a good place to explain to others in your company what the repo is for–you can edit it later), and click “Create repository”.
  1. Click on the new repository name, and select the green “<>Code” button. Ensure the “HTTPS” tab is selected (orange bar underneath), then copy the https:// URL shown below.
  2. Go to your instance of Nautobot and navigate to Extensibility -> Git Repositories. Click the blue “+Add” button and fill in a “Name” (human-readable) and paste into “Remote URL” the repo link that you just copied above.
  1. Leave “Branch” set to “main” unless the primary branch of your repo is named differently.
  2. You need to authenticate to GitHub to use this new repo with Nautobot, but because Username and Token are deprecated in at least 1.5.9 and up, we’ll have to create a Secrets Group with your token. Of course, that means you first need to create a token, as discussed in the next section. For now, leave all this blank and we’ll come back to it.
  1. Select the type of data your repo contains in the “Provides” drop-down menu. For instance, if this is repo contains configuration backups, select “backup configs” from the list. There should be only one type–if you need more types of data, create another repo for each.
  2. If you have configured the token and associated secrets group already, you can click “Create & Dry Run”. If not, you can still click it, but the dry run will fail until you come back and edit this repo to include a working secrets group. Otherwise, leave this window open and proceed with the personal access token and secrets group setup in another window, then return and complete creation.

Personal Access Tokens in GitHub

A personal access token is a long string of random characters generated by a system which you have permissions to use. This token takes the place of a username and password when accessing the system programmatically, while still mostly ensuring the system is secure. I say “mostly”, because if your token falls into the wrong hands, those hands will be able to do everything that you can do with the token, just like with a password. So, it’s a good idea to imbue the token with the bare minimum in terms of permissions needed to accoplish the task at hand, and of course take all reasonable security precautions with it.

There are two kinds of personal access tokens supported by GitHub at the moment–Classic, and Fine-grained, which is currently in Beta. Classic tokens are associated with your GitHub user, and the permissions you can give to the token are fairly broad. Fine-grained tokens, on the other hand, can be for a user or an organization, and you can, as the name suggests, be much more finely-detailed in the way you assign its permissions. I’ve been using the latter with no problems for the last few months with Nautobot 1.5.9, so I’m going to outline how to create one below, but I think it’s fair to say Classic tokens are simpler to use, if not as secure or precise in terms of permissions. They’re also more established and have been in use for a long time, so there should be no trouble finding documentation if these fine-grained token instructions do not suffice.

Generating a Token

Going back to GitHub:

  • Click on the drop-down under your user icon in the upper right, and select “Settings”.
  • Find “Developer settings” at the bottom of the left-hand sidebar and select it.
  • Under “Personal access tokens”, select “Fine-grained tokens (Beta)”.
  • Click the “Generate new token” button in the upper right.
  • Enter a Token name and Description, and set an Expiration as required.
  • Choose a Resource owner, which can be yourself or any organizations you’re in.

Repository access

Next you’ll need to decide which repositories this token can access. When choosing anything other than “Public Repositories”, which are read-only, it’s generally safest to choose “Only select repositories” in order to minimize potential harm if the token is exposed.

Permissions

This section can be really overwhelming–it has a link to GitHub’s permissions documentation but in the beginning even this can be more confusing than helpful. To give a sense of how little is needed for using repos with nautobot, however, the fine-grained token I’m using for Golden Config only has access to the repos I use specifically for that purpose, and its permissions are:

  • read access for metadata
  • read-write access for code, commit statuses, and pull requests
  • no organization permissions

So it’s probably best to err on the side of minimal permissions, and generate a new token later if you find you need more.

Overview

Finally, we can complete the generation process:

  • Read through the permissions summarized for your repositories and account to ensure it makes sense.
  • Make a note of when the token will expire - I find it helpful to put this on my calendar with a reminder so I don’t get caught unaware with automations suddenly not working.
  • If it all looks good, click the green “Generate token” button.

Important: Copy the new token and do not navigate away or close the page until you’ve saved the token somewhere secure, such as a text file on your local machine.

Using the Token

Next you have to decide if you want to keep the token in a text file for the longer term, or an environment variable. Either one works for Secrets in Nautobot, but generally speaking the environment variable is better since it helps users avoid the inadvertent pushing of sensitive information to GitHub. Arguably a vault is an even better solution because it’s actually secure, but it’s more complicated too, and outside the scope of this post, which assumes a lab or test setup rather than production. So, we’ll use an environment variable, and assume the docker compose version of nautobot:

  • ssh to nautobot and sudo to the nautobot user, then change directories to the main nautobot docker compose directory:
    ssh nautobot.yourcompany.net
    sudo -iu nautobot
    cd nautobot-docker-compose/
    
  • Edit the local.env file (use a different editor if “vi” is not your thing):
    vi local.env
    
  • And insert a new variable such as NAUTOBOT_GC_GITHUB_TOKEN somewhere that makes sense to you, e.g. at the end:
    NAUTOBOT_SUPERUSER_EMAIL=admin@yourcompany.net
    NAUTOBOT_SUPERUSER_PASSWORD=admin
    NAUTOBOT_SUPERUSER_API_TOKEN=0123456789abcdef0123456789abcdef01234567
    NAUTOBOT_GC_GITHUB_TOKEN=012345678901234567890123456789012345678901234567890123456789
    
  • Save the file, then refresh the docker compose containers that use it (may need to do docker compose down first if the following does not refresh the nautobot containers):
    docker compose up -d
    

If you’re not using the containerized version of Nautobot, assign and/or export the variable as you’d normally do in your shell, such as bash.

Secrets Groups in Nautobot

To use our token in the environment variable we just created, we need to next go back to the Nautobot UI and set up a Secret, and then a Secrets Group. This way, no actual secrets are stored in the nautobot database, and the secrets group can then be referenced in our repo setup under the Extensibility menu.

Create the Secret

  1. Navigate to the “Secrets” menu, then the “Secrets” submenu.
  2. Click the blue “+Add” button.
  1. Fill in Name (Slug will automatically populate as before), and a Description to explain to your colleagues what this is for.
  2. Under the Provider drop-down, select “Environment Variable”.
  1. For Parameters, where it says Variable, enter the name of the one you added to local.env in the previous section, which is NAUTOBOT_GC_GITHUB_TOKEN in this example.
  2. Scroll down and click “Create”.

Create the Secrets Group

We’re almost there–just need to add that secret to a group.

  • Navigate to Secrets->Secret Groups from the nautobot menu bar.
  • Click the blue “+Add” button.
  • Fill in “Name” and “Description”, then scroll down to Secret Assignment:
  • In the first “Access type” drop-down, select HTTP(S).
  • On the same row, set “Secret type” to “Token”.
  • Also on the same row, select the name of the secret you created in the last section.
  • Scroll down and click the blue “Create” button.

Go Back to Repo Setup

Now that you have configured all the required Secrets and Secrets Groups, you can go back to Step 6 of new repo creation to complete the authentication section. If you already did “Create & Dry Run” before and had it fail, not to worry. Just Edit the repo (orange pencil button) instead of Add in Step 4, choose the group you just created in the Secrets Group drop-down, and click “Update & Dry Run”.

Categories:

Updated: