Developer workflow

Keep your track building under control using CI/CD pipelines

This guide explains how to maintain a developer workflow based on Git and GitHub Actions for your track building with development-to-production testing and promotion.

Why would you maintain a developer workflow?

The benefit of a developer workflow is that you can change and test a track without disrupting production tracks. So, by maintaining a developer workflow, you ensure your content is free from errors that could cause a bad experience for learners.

Warning

The developer workflow will cause track challenge IDs to be overwritten whenever a pull request is merged. There is no easy fix for this at the moment because of the way tracks are ordered.

Overview

The bottom line of the developer workflow is that you maintain a development and production version of a track. In this setup, you change the development version until you are satisfied and it is error-free. And then you merge the changes into the production version, making the updated track available to your learners.

At a high level, the developer workflow looks like this:

1. Create a new branch for your development work.

2. Run a GitHub Action to create a development version of your production track.

3. Modify the development version of the track (via the Instruqt platform, or locally).

4. Run another GitHub Action to restore the production track's attributes (ID, name, etc).

5. Merge the pull request.

As mentioned, this is only a high-level overview. The following sections describe all the steps and components in the developer workflow.

Before you begin

You need the following to maintain the developer workflow:

• A GitHub account.

• Instruqt CLI on your machine.

• GitHub CLI on your machine (optional).

• Git on your machine (optional).

Maintain a developer workflow

Initial configuration

First, you need to set up a repository. These steps are performed once.

Web UI

1. Open the Instruqt Skeleton repository and select Use this template.

2. Provide your new repository a name and select Create repository from template.

3. Open a new tab and navigate to your organization's Instruqt page.

4. Select Team Settings, followed by API keys. If there is no key present, then create one. Otherwise, select Copy to clipboard.

5. Return to your repository and select Settings from the top menu. On the left side, expand Secrets and select Actions. Select New repository secret. Configure the secret name as INSTRUQT_TOKEN and paste your organization's API key as the value.

6. In the same Secrets and Variables section select the Variables tab. Create a new repository variable called TRACK_DIR and set the value to instruqt-tracks. This must match the name of the directory in your repo where all tracks are stored. The skeleton template you copied already has this directory in it.

7. From within the Settings menu, select Actions > General and scroll down to Workflow Settings. Enable Read and Write permissions.

8. Pull the latest versions of your tracks to your local machine using the Instruqt CLI (apologies...there is no method of doing this via a Web UI):

   instruqt track pull <org-slug>/<track-slug>

9. From your repository's main page, navigate into the instruqt-tracks directory. Select Add file followed by Upload files. Drag and drop all of your track directories and select Commit changes.

10. Make sure that any tracks that you do not want tested have one of the following tags: no-ci, ci-skip, or skip-ci. All other tracks in the directory will become part of your automated tests.

CLI

1. Open the Instruqt Skeleton repository and select Use this template.

2. Provide your new repository a name and select Create repository from template. Choose the Private option to keep your track code hidden from public view.

3. Open a new tab and navigate to your organization's Instruqt page.

4. Select Team Settings, followed by API keys. If there is no key present, then create one. Otherwise, select Copy to clipboard

5. Return to your repository and select Settings from the top menu. On the left side, expand Secrets and select Actions. Select New repository secret. Configure the secret name as INSTRUQT_TOKEN and paste your organization's API key as the value.

6. In the same Secrets and Variables section select the Variables tab. Create a new repository variable called TRACK_DIR and set the value to instruqt-tracks. This must match the name of the directory in your repo where all tracks are stored. The skeleton template you copied already has this directory in it.

7. Clone the repository to your local machine (The URL is available via the Code button on your repositories main page):

   git clone <your_new_repository_url> 

8. Navigate into the repository's instruqt-tracks directory and pull your tracks:

   cd <repository_dir>/instruqt-tracks
   instruqt track pull <org-slug>/<track-slug>

9. Add, commit, and push your changes to the repository:

   git add .
   git commit -m "Adding tracks to repository"
   git push -u origin main

10. Make sure that any tracks that you do not want tested have one of the following tags: no-ci, ci-skip, or skip-ci. All other tracks in the directory will become part of your automated tests.

Initial Configuration Walkthrough

From this point forward, you can manage all changes to your tracks with the Developer Workflow. If you add new tracks, make sure to tag any that should not be part of automated testing with the no-ci tag.

Developer workflow

Repeat the following steps each time you modify your production tracks:

Web UI

From the repository that contains your Instruqt tracks:

1. Create a new branch by selecting Main > View all branches > New branch.

2. Select Actions from the top menu of your repository. On the left side, select the copy-prod-track-to-dev workflow. On the right side, expand the Run workflow dropdown menu, and select your new branch name. Next, provide the slug of the track you intend to modify. Finally, select Run workflow. You must run this workflow on your dev branch, and not on the main/master branch which is not allowed for safety purposes. Also note that if you already have a dev version of this track it will be overwritten with the prod version to provide a clean starting environment.

3. Go to your organization's Instruqt page and modify the development version of your track until you are satisfied with the changes. Test your track in the UI until you are happy with its performance. When your track is working smoothly and all check/solve scripts are functional, turn off maintenance mode. You must disable maintenance mode on the dev track to proceed!

4. Once the development version of your track is ready, return to GitHub and run the prepare-dev-for-pull-request workflow from the Actions menu. Provide the same branch and track slug you used in the copy-prod-track-to-dev workflow.

5. Create a pull request by selecting Pull requests in the top menu of your repository, followed by New pull request. Indicate your new branch, and select Create pull request.

6. Have a colleague review your work, make sure the tests all pass, and merge the pull request! Once merged, the changes will be applied to the production version of your track and production will receive another round of post-merge testing. You can review the results of the tests in the Actions tab of your repo.

CLI

1. Change into the directory containing your repository and create a new branch. Make sure to push the new branch to GitHub as well:

   cd <repository_dir>
   git pull
   git checkout -b my-new-content
   git push -u origin my-new-content

2. Run the copy-prod-track-to-dev workflow, providing the branch and track slug you wish to modify:

   gh workflow run "copy-prod-track-to-dev" -F "slug=<track-slug>" -r my-new-content

3. Pull the changes made by the workflow (the name and IDs will be modified):

   git pull

4. Go through your normal workflow of pushing, testing, and validating your Instruqt track using the instruqt command. Make sure your final local changes are reflected in the track on Instruqt, because it will be used as the source of truth for the development version of the track.

5. Add, commit, and push your changes to GitHub:

   # If you haven't yet, run `instruqt track push` before this!
   git add .
   git commit -m "Adding new content!"
   git push

6. Once you are satisfied with your development track, and the latest changes have been pushed to Instruqt, run the prepare-dev-for-pull-request workflow:

   gh workflow run "prepare-dev-for-pull-request" -F "slug=<track-slug>" -r my-new-content 

7. Create a pull request by selecting Pull requests in the top menu of your repository, followed by New pull request. Indicate your new branch, and select Create pull request.

8. Have a colleague review your work, and merge the pull request! Once merged, the changes will be applied to the production version of your track.