frau-ci v1.42.2

frau-ci

Overview

This repository contains CI hooks that assist in updating the version of your Free Range App (FRA). After installing via npm, the following commands will become available, and can be run from your travis.yml file (or other CI script):

frauci-update-version:

• Use this script to automatically update and tag a new version of your npm module as brightspace-bot. This script is expected to run during a Travis build. By default this script will update the minor version of your npm module but can be changed to default to major, patch, or skip. By using increment major, increment minor, increment patch or skip version notation inside your merge message, you can overwrite the default version upgrade to the position of your choice.

frauci-get-version:

• Use this script to get the updated version in the package.json file. When running in travis you may need to set TRAVIS_TAG environment variable to the updated version, this script can help you with that.

frauci-queue-message:

• Run as the last step in your CI pipeline - Use this to update the LE to use the latest FRA version, and (optionally) kick of a test run via Mastiff. Note: You must configure a Jenkins job in the following location in order for your FRA version to be updated in Brightspace: http://prod.build.d2l/job/EDU-pyxis/job/Mimir/job/RollTheFraken/job/FRA/. See the FRA Pipeline documentation in docs.dev for more details.

frauci-get-userstory

• Use this script to scrape the user story out of the last commit (This commit should be a merge). You can then set this to the USER_STORY environment variable which will be used in frauci-queue-message to pass along to the LE update. This is a way to connect the automated core updates to rally stories.

Installation

Add frau-ci to your package.json: npm install frau-ci --save-dev.

Configuration

To use frau-ci as part of your build pipeline, ensure that the following config values are defined in your package.json:

Update Version Configs:

travis.yml:

env:
  global
  #GITHUB_RELEASE_TOKEN (encryptedToken) - Token used to commit to github as specified user (default `brightspace-bot`)
  - secure: encryptedToken
  - REPO_NAME=<name of the github repo>
  - OWNER_NAME=<name of the github repo owner>

Note: Refer to TravisCI documentation regarding encrypting variables

Queue Message Configs:

package.json:

"config": {
  "frauPublisher": {      -- https://github.com/Brightspace/frau-publisher/blob/master/README.md
    "files": "<path that contains your compiled application... typically: './dist/**'>",
    "moduleType": "app|lib",
    "targetDirectory": "cdn directory for your app",
    "creds": {
      "key": "your key",
      "secretVar": "Name of the variable in travis.yml containing your encrypted S3 secret key"
    },
    "devTagVar": "TRAVIS_COMMIT",
    "versionVar": "TRAVIS_TAG"
  },
  "ironIO": {
    "queueName": "fra-versions"
  }
}

Note: The frauPublisher config block in package.json is the same set of configs used for the frau-publisher npm module (a dependency of frau-ci). You do not need to duplicate any of the configs in that block if you have already set them up.

travis.yml:

env:
  global
  #IRON_IO_TOKEN (encryptedToken) - for iron io queue usage
  #IRON_IO_ID (encryptedID) - for iron io queue usage
  - secure: encryptedToken
  - secure: encryptedID
  - FRA_NAME=<name of the FRA, as referenced in Brightspace. eg. insights-class-insights>
  - FRA_LMS_URL=<.git URL to the Brightspace repo where the FRA is hosted. eg. https://git.dev.d2l/scm/an/ap.git>
  - FRA_LMS_PATH=<path to the fra .json file in the FRA_LMS_URL repo. default: insightsPortal/_config/AppLoader/Apps/{FRA_NAME}.json>
  - FRA_KEY=<FRA key in Brightspace. default: urn:d2l:fra:class:{FRA_NAME}>
  - RUN_MASTIFF=<Optional: run the Mastiff test suite before update. 'true'|'false'>

Note: Refer to TravisCI documentation regarding encrypting variables

Usage

The Update Version or Queue Message commands can be run either directly on the console CLI (assuming dependencies are installed), or specified as a script in package.json. Arguments may be passed directly on the CLI, or may be configured in package.json/travis.yml.

Update Version

Call from a node command with frauci-update-version (ensure travis.yml contains necessary parameters found in Configuration above), or call via CLI with optional params listed below:

frauci-update-version   --ownerName|-o         defaults to OWNER_NAME global env variable or 'Brightspace'
                        --repoName|-r          *defaults to REPO_NAME global env variable
                        --packageFile|-f       defaults to './package.json'
                        --branch|-b            defaults to 'master'
                        --username|-u          defaults to 'brightspace-bot'
                        --email|-e             defaults to 'BrightspaceGitHubReader@d2l.com'
                        --releaseToken|-t      *defaults to GITHUB_RELEASE_TOKEN global env variable
                        --tagPrefix|-p         defaults to TAG_PREFIX global env variable, or 'v' if ownerName is 'BrightspaceUI' or 'Brightspacehypermediacomponents'; otherwise, ''
                        --defaultIncrement|-d  defaults to DEFAULT_INCREMENT global env variable or 'minor'. 'major'|'minor'|'patch'|'skip'

-- Values with a * must have either the CLI parameter passed in, or the travis.yml global environment variables populated.

Important: After running frauci-update-version you must set the TRAVIS_TAG environment variable to the updated version. You may do so by running export TRAVIS_TAG=$(frauci-get-version). Also remember that you must build your project after updating its version. Otherwise the metadata will be incorrect.

Queue Message

Call from a node command with frauci-queue-message (ensure travis.yml contains necissary parameters found in Configuration above), or call via CLI with params listed below:

frauci-queue-message    --files|-f            *defaults to config.frauPublisher.files from package.json
                        --moduleType|-m       *defaults to config.frauPublisher.moduleType from package.json
                        --targetDirectory|-t  *defaults to config.frauPublisher.targetDirectory from package.json
                        --key|-k              *defaults to config.frauPublisher.creds.key from package.json
                        --secretVar|-s        *defaults to config.frauPublisher.creds.secretVar from package.json
                        --version|-v          *defaults to config.frauPublisher.versionVar from package.json

-- Values with a * must have either the CLI parameter passed in, or the package.json config value populated.

Get Version

Call from a node command with frauci-get-version. This will print the current version listed in the package.json. If called after frauci-update-version this will print the new version. This comes in handy when wanting to set the TRAVIS_TAG environment variable in travis before publishing your FRA.
Example usage in travis.yaml to set TRAVIS_TAG. export TRAVIS_TAG=$(frauci-get-version). Make sure to call this AFTER frauci-update-version when publishing the new version!

frauci-get-version     --packageFile|-f      defaults to './package.json'
                       --tagPrefix|-p        defaults to TAG_PREFIX global env variable or 'v' if ownerName is 'BrightspaceUI', 'Brightspacehypermediacomponents'; otherwise, ''

Get User Story

Call from a node command with frauci-get-userstory. This will attempt to scrape either a user story or defect number from the last commit message on this repo. If you are going to use this in your travis.yaml file make sure to run it BEFORE you update the version, or it will try to scrape the user story from the version update commit, which will have no users story.

frauci-get-userstory    --ownerName|-o        defaults to OWNER_NAME global env variable or 'Brightspace'
                        --repoName|-r         *defaults to REPO_NAME global env variable
                        --branch|-b           defaults to 'master'
                        --username|-u         defaults to 'brightspace-bot'
                        --email|-e            defaults to 'BrightspaceGitHubReader@d2l.com'
                        --releaseToken|-t     *defaults to GITHUB_RELEASE_TOKEN global env variable

Example Usage:

in your package.json:

"scripts": {
 "build": "<build steps go here>",
 "publish-release": "npm run build && frau-publisher && frauci-queue-message",    -- using https://github.com/Brightspace/frau-publisher
}

in your travis.yml:

script:
- export USER_STORY=$(frauci-get-userstory)
- frauci-update-version
- export TRAVIS_TAG=$(frauci-get-version)
- npm run publish-release