Secrets

How to use secrets in lifecycle scripts.

Secrets are a secure way to store and maintain sensitive values (e.g. credentials or API tokens) for use in lifecycle scripts. Secrets are write-only, which prevents all users from reading their values. Secrets are defined on team level, allowing them to be used by multiple tracks.

Secrets can only be created/updated by team Owners, and can be used by Content Creators.

View secrets

Follow the steps bellow to access the Secret management page.

🌐 Web UI

1. Click Settings -> Secrets.

2. A table will show detailing all your teams current Secrets

💻 Instruqt CLI

1. Open a new terminal.

2. Enter the following command:

   instruqt secrets list

   ↳ Instruqt CLI lists all secrets for the currently configured team. The output looks something like this:

   ==> Listing secrets for team TEAM_NAME
       NAME              CREATED                 UPDATED                 DESCRIPTION
       SECRET_KEY_1      2022-08-16T13:43:43     2022-08-16T13:43:43     Description of secret one
       SECRET_KEY_2      2022-08-16T13:44:23     2022-08-16T15:23:06     Description of secret two
   

Add a secret

Follow the steps below to add a new secret to your team.

🌐 Web UI

1. Click Settings -> Secrets.

2. Click the Create button on the top right of the page

3. In the Name field, enter a name or key of the secret. Secrets only accept letters, numbers and underscores (e.g. MY_SECRET_KEY).

4. In the Description field, enter a description of the secret.

5. In the Value field, enter the actual secret value.

6. Click Save Changes.

💻 Instruqt CLI

1. Open a new terminal.

2. Enter the following command:

   instruqt secrets create SECRET_NAME "SECRET_VALUE" \ 
       --description="SECRET_DESCRIPTION"

   ⇨ Replace SECRET_NAME with the name of the secret you would like to create. ⇨ Replace SECRET_VALUE with the value of the secret. ↳ Instruqt CLI creates the new secret. The output looks something like this:

   ==> Create secret SECRET_NAME for team TEAM_NAME
       OK

The description should help content creators understand how the Secret should be used. It's recommend to keep the descriptions brief but indicative of how the secret should be used.

Update a secret

🌐 Web UI

1. Click Settings -> Secrets.

2. Click ••• on the secret you would like to update and select Update.

3. In the Description field, enter a new description if applicable.

4. In the Value field, enter the new secret value, this is mandatory for updates.

5. Click Save changes.

💻 Instruqt CLI

1. Open a new terminal.

2. Enter the following command:

   instruqt secrets update SECRET_NAME "SECRET_VALUE" 

   ⇨ Replace SECRET_NAME with the name of the secret you would like to create. ⇨ Replace SECRET_VALUE with the value of the secret. ↳ Instruqt CLI creates the new secret. The output looks something like this:

   ==> Update secret SECRET_NAME for team TEAM_NAME
       OK

When updating a Secret the value is always required. If you would like update the description only the previous secret value should be used.

Delete a secret

🌐 Web UI

1. Click Settings -> Secrets.

2. Click ••• on the secret you would like to delete and select Delete. ↳ A delete confirmation is shown

3. Click Confirm. ↳ The secret is deleted and removed and not available on the secrets table.

💻 Instruqt CLI

1. Open a new terminal.

2. Enter the following command:

   instruqt secrets delete SECRET_NAME 

   ⇨ Replace SECRET_NAME with the name of the secret you would like to delete. ↳ Instruqt CLI creates the new secret. The output looks something like this:

   ==> Delete secret SECRET_NAME for team TEAM_NAME
       OK

Once a Secret has been deleted it will not be possible to recover the value that was previously stored.

Add secrets to tracks

To make use of a Secret value in a tracks lifecycle scripts the track must to be granted access to the secret.

🌐 Web UI

1. Click the track to which you want to give secret access.

2. In the Sandbox section, click Edit to open the Sandbox page.

3. Click + Add a secret.

4. Select the secrets you would like access in your track scripts by clicking the checked box.

5. Click Save.

💻 Instruqt CLI

Add the following code into config.yml, where SECRET_NAME is the name of the secret you would like to make use of in the tracks lifecycle scripts.

secrets:
- name: SECRET_NAME

↳ Your config.yml file should be similar to this:

version: "3"
secrets:
- name: MY_SECRET_KEY
- name: ANOTHER_SECRET_KEY

Adding a Secret to your track sets an environment variable which is available for the duration of a tracks lifecycle scripts.

Example

Consider the following example, making an authorised curl request using a username and password: 1. Add a Secret with SITE_PASSWORD as the name and the password as the value.

2. Add the following to your lifecycle script:

curl --user name:${SITE_PASSWORD} http://www.example.com