Developer workflow
Keep your track building under control using CI/CD pipelines
Last updated
Was this helpful?
Keep your track building under control using CI/CD pipelines
Last updated
Was this helpful?
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.
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.
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.
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:
Create a new branch for your development work.
Run a to create a development version of your production track.
Modify the development version of the track (via the Instruqt platform, or locally).
Run another GitHub Action to restore the production track's attributes (ID, name, etc).
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.
You need the following to maintain the developer workflow:
First, you need to set up a repository. These steps are performed once.
Provide your new repository a name and select Create repository from template.
Select Team Settings, followed by API keys. If there is no key present, then create one. Otherwise, select Copy to clipboard.
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.
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.
From within the Settings menu, select Actions > General and scroll down to Workflow Settings. Enable Read and Write permissions.
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.
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.
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.
Repeat the following steps each time you modify your production tracks:
From the repository that contains your Instruqt tracks:
Create a new branch by selecting Main > View all branches > New branch.
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.
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.
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.
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.
A account.
on your machine.
on your machine (optional).
on your machine (optional).
Open the repository and select Use this template.
Open a new tab and navigate to your organization's .
Pull the latest versions of your tracks to your local machine using the (apologies...there is no method of doing this via a Web UI):
Open the repository and select Use this template.
Open a new tab and navigate to your organization's .
Go to your organization's 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!