Instruqt Docs
PlatformGithub
Search
⌃K
Links

Maintain a developer workflow

Keep your track building under control.

WARNING

The developer workflow template repo is being updated and some of the instructions below may be out of date. If you wish to implement the GitOps workflow describe below please reach out to Instruqt customer support or your SE before you get started. These docs will be updated shortly to update the changes.

Maintain a developer workflow

This guide explains how to maintain a developer workflow based on Git and GitHub 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.

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. 1.
    Create a new branch for your development work.
  2. 2.
    Run a GitHub Action to create a development version of your production track.
  3. 3.
    Modify the development version of the track (via the Instruqt platform, or locally).
  4. 4.
    Run another GitHub Action to restore the production track's attributes (ID, name, etc).
  5. 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. If you want to watch a demonstration of this workflow, we've created the following video:
Instruqt Developer Workflow Demo

Before you begin

You need the following to maintain the developer workflow:

Maintain a developer workflow

Initial configuration

First, you need to set up a repository. These steps are performed once.
Web UI
CLI
  1. 1.
    Open the Instruqt Skeleton repository and select Use this template.
  2. 2.
    Provide your new repository a name and select Create repository from template.
  3. 3.
    Open a new tab and navigate to your organization's Instruqt page.
  4. 4.
    Select Team Settings, followed by API keys. If there is no key present, then create one. Otherwise, select Copy to clipboard.
  5. 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. 6.
    From within the Settings menu, select Actions > General and scroll down to Workflow Settings. Enable Read and Write permissions.
  7. 7.
    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>
  8. 8.
    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.
  9. 9.
    Select Actions from the top menu of your repository. On the left side, select the generate workflow. On the right side, expand the Run workflow dropdown and select Run workflow. This workflow will generate a track-slugs.yml file to store your track slugs and IDs.
  1. 1.
    Open the Instruqt Skeleton repository and select Use this template.
  2. 2.
    Provide your new repository a name and select Create repository from template.
  3. 3.
    Open a new tab and navigate to your organization's Instruqt page.
  4. 4.
    Select Team Settings, followed by API keys. If there is no key present, then create one. Otherwise, select Copy to clipboard
  5. 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. 6.
    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>
  7. 7.
    Navigate into the repository's instruqt-tracks directory and pull your tracks:
    cd <repository_dir>/instruqt-tracks
    instruqt track pull <org-slug>/<track-slug>
  8. 8.
    Add, commit, and push your changes to the repository:
    git add .
    git commit -m "Adding tracks to repository"
    git push -u origin main
  9. 9.
    Run the generate workflow remotely via the GitHub CLI, or via the Actions menu:
    gh workflow run "generate"
From this point forward, you can manage all changes to your tracks with the Developer Workflow. If you add new tracks, make sure to run the generate workflow again.

Developer workflow

Repeat the following steps each time you modify your production tracks:
Web UI
CLI
  1. 1.
    Navigate to the repository that contains your Instruqt tracks.
  2. 2.
    Create a new branch by selecting Main > View all branches > New branch.
  3. 3.
    Select Actions from the top menu of your repository. On the left side, select the convert 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.
  4. 4.
    Go to your organization's Instruqt page and modify the development version of your track until you are satisfied with the changes.
  5. 5.
    Once the development version of your track is ready, return to GitHub and run the promote workflow from the Actions menu. Provide the same branch and track slug you used in the convert workflow.
  6. 6.
    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.
  7. 7.
    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.
  1. 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. 2.
    Run the convert workflow, providing the branch and track slug you wish to modify:
    gh workflow run "convert" -F "slug=<track-slug>" -r my-new-content
  3. 3.
    Pull the changes made by the workflow (the name and IDs will be modified):
    git pull
  4. 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. 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. 6.
    Once you are satisfied with your development track, and the latest changes have been pushed to Instruqt, run the promote workflow:
    gh workflow run "promote" -F "slug=<track-slug>" -r my-new-content
  7. 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. 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.
Inform your learners that the new track is available. And reward yourself because you are a true Instruqt master now. For example, by playing this Instruqt based 🕹️Palace Arcade.
Previous
Monitor tracks played via a track invite
Next
View track logs
Last modified 1d ago