Job Templates

We have created reusable templates that you can extend to configure the jobs needed for your app's pipeline. All the templates can be found in ./pipelines/templates

`.initiate`

Used to manually trigger a pipeline by being the first job and following jobs needing initiate to run.

`.initiate` Template

Introduced a manually triggered step to run builds

.initiate: # extendable template name, e.g. extends: .initiate 
  stage: test # extends the "test" stage
  image: registry.gitlab.com/investec/docker/build/angular/ng:10-nx # angular docker image
  script: # list of scripts to run
    - echo "Envs will now build" # output a message
  when: manual # run manually by clicking play button in pipeline
  only: # run only if below conditions are met
    refs: # git refrences
      - master # only run if changes in master branch

Tip

Having an initiate job is optional, if you wanted to automatically run your pipelines every time you would not use this

Example extending `.initiate`

extending .initiate template for my-app

my-app-initiate:
  extends: .initiate
  only:
    changes: [ apps/app-platform-my-app/**/* ] # only run if changes in apps/app-platform-my-app/**/*

`.unit-test`

Used to run your unit tests.

`.unit-test` Template

Run unit tests if changes in master

.unit-test: # extendable template name, e.g. extends: .unit-test
  stage: test # extends the "test" stage
  image: registry.gitlab.com/investec/docker/build/angular/ng:12-nx # angular docker image
  only: # run only if below conditions are met
    refs: # git refrences
      - master # only run if changes in master branch

Example extending `.unit-test`

extending .unit-test template for my-app

my-app-unit-tests:
  extends: .unit-test
  only:
    changes: [ apps/app-platform-my-app/**/* ] # only run if changes in apps/app-platform-my-app/**/*
  script:
    - npm i # this should be removed as dependencies should be added to the docker image to speed up test times
    - ng test --project=my-app --browsers=ChromeHeadlessCI --watch=false # run unit tests for my-app

`.build`

Used to build your angular app.

`.build` Template

Build your app if changes in master

.build: # extendable template name, e.g. extends: .build
  stage: build # extends the "build" stage
  image: $NODE_IMAGE_URL # angular docker image from Gitlab CI variables
  script: # list of scripts to run
    - npm i # this should be removed as dependencies should be added to the docker image to speed up test times
    - node --max_old_space_size=8192 node_modules/@angular/cli/bin/ng build --project $TARGET_PROJECT --base-href $TARGET_BASE_HREF -c $TARGET_ENV
    - tar -czvf $TARGET_PROJECT.$TARGET_ARTIFACT.$CI_PIPELINE_ID.tar.gz $TARGET_DIST_DIR
    - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file $TARGET_PROJECT.$TARGET_ARTIFACT.$CI_PIPELINE_ID.tar.gz ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/$TARGET_PROJECT/0.0.$CI_PIPELINE_ID/$TARGET_PROJECT.$TARGET_ARTIFACT.$CI_PIPELINE_ID.tar.gz'
  only: # run only if below conditions are met
    refs: # git refrences
      - master # only run if changes in master branch

Example extending `.build`

extending .build template for my-app

my-app-build-staging:
  extends: .build
  only:
    changes: [ apps/app-platform-my-app/**/* ]
  needs: [ my-app-initiate ]
  variables:
    TARGET_ENV: staging # e.g. staging, beta, production
    TARGET_ARTIFACT: staging # the target angular artifact configuration
    TARGET_PROJECT: app-platform-my-app # angular project directory name
    TARGET_BASE_HREF: /my-app/ # base href used in angular build configuration 
    TARGET_DIST_DIR: ./dist/apps/app-platform-my-app # angular artifact dist directory

`.deploy`

Used to deploy your angular app.

`.deploy` Template

Deploy your app if changes in master

.deploy: # extendable template name, e.g. extends: .deploy
  stage: deploy # extends the "deploy" stage
  image: $WRANGLER_IMAGE_URL # angular docker image from Gitlab CI variables
  script: # list of scripts to run
    - CHANGE_ID=$(cat CHANGE_ID.txt)
    - npm i @investec/cloudflare-worker-site-generator
    - cf-generate --copy
    - cf-generate --wrangler --application $TARGET_PROJECT --environment $TARGET_ENV --urls $TARGET_URI --bucket $TARGET_BUCKET --zone $TARGET_CF_ZONE --account $CF_ACCOUNT_ID
    - cf-generate --worker --uri $TARGET_CF_URI
    - 'wget --header="JOB-TOKEN: $CI_JOB_TOKEN" ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/$TARGET_PROJECT/0.0.$CI_PIPELINE_ID/$TARGET_PROJECT.$TARGET_ENV.$CI_PIPELINE_ID.tar.gz'
    - tar -xzvf $TARGET_PROJECT.$TARGET_ENV.$CI_PIPELINE_ID.tar.gz
    - CF_API_TOKEN=$CLOUDFLARE_API_TOKEN_WORKERS wrangler publish --env $TARGET_ENV
    - echo $CHANGE_ID > CHANGE_ID.txt
  environment:
    name: $TARGET_CF_ENV_NAME
    url: $TARGET_URI
  when: on_success
  only: # run only if below conditions are met
    refs: # git refrences
      - master # only run if changes in master branch
  artifacts:
    when: on_success
    expire_in: 1 days
    paths:
      - CHANGE_ID.txt

Example extending `.deploy`

extending .deploy template for my-app

pc-uk-deploy-staging:
  extends: .deploy
  only:
    changes: [ apps/app-platform-my-app/**/* ]
  needs: [ pc-uk-build-staging ]
  variables:
    TARGET_ENV: staging
    TARGET_URI: "['loginstg.secure.investec.com/my-app*']"
    TARGET_CF_ZONE: $SECURE_INVESTEC_COM_CF_ZONE_ID
    TARGET_CF_URI: my-app
    TARGET_CF_ENV_NAME: my-app-staging
    TARGET_PROJECT: app-platform-my-app
    TARGET_BUCKET: app-platform-my-app

`.create-change`

Used to create a change request for your deployment.

Logging a change requires lots of variables. You will also need the sys_id of your Business Service from ServiceNow, below as SN_SYS_ID. Also the sys_id of the person logging the change. In the example below the person who made the commit, stored in SN_REQ_BY. See below for bash to extract the committers email address. If CAB is required set the cab_required and CAB group sys_id (the latter shown as SN_CAB_GROUP_SYS_ID). The last two parameters are optional and is not required to be set. cab_required will default to false if omitted.

`.create-change` Template

Create change request if changes in master

.create-change:
  stage: create-change
  image:
    name: registry.gitlab.com/investec/docker/tooling/servicenow-tools:latest
  environment:
    name: staging
  only:
    refs:
      - master
  variables:
    SN_SYS_ID: $SN_SYS_ID
    SN_APP_NAME: $SN_APP_NAME
    AFFECTED_CI_REQUIRED: "false"
    SN_AFFECTED_CI: $SN_AFFECTED_CI
    BACKOUT: "Pipeline - $CI_PIPELINE_URL"
    TEST_PLAN: "Pipeline - $CI_PIPELINE_URL"
    JUSTIFICATION: "Pipeline - $CI_PIPELINE_URL"
    IMPL_PLAN: "Execute deploy job on $CI_PIPELINE_URL"
    CATEG: "Application"
    CHG_SRC: "operational/bau"
    RISK: "4"
    SN_ENV: $SN_ENV
    CAB_REQUIRED: "true"
    CAB_APPROVAL_GROUP: $CAB_APPROVAL_GROUP
  script:
    - COMMIT_AUTHOR=$(./io-resources/scripts/get_commit_author.sh "$GITLAB_ACCESS_TOKEN" "$CI_PROJECT_ID" "$CI_COMMIT_SHA")
    - echo "$COMMIT_AUTHOR done"
    - SN_REQ_BY=$(get_user_id "$SNOW_API_TOKEN" "$SN_ENV" "$COMMIT_AUTHOR")
    - echo "SN_REQ_BY done"
    - SN_SHORT_DESC="Investec Online Front-end Release v$(./io-resources/scripts/get_version_from_package.sh './package.json') $CHANGE_DESC" # $CHANGE_DESC build this up from change log
    - SN_DESC="$SN_SHORT_DESC"
    - NOW=$(date +'%m/%d/%Y %T')
    - CHANGE_ID=$(create_change "$SNOW_API_TOKEN"
      "$SN_ENV"
      "$SN_DESC"
      "$SN_SHORT_DESC"
      "$SN_SYS_ID"
      "$SN_REQ_BY"
      "$SN_REQ_BY"
      "$BACKOUT"
      "$TEST_PLAN"
      "$JUSTIFICATION"
      "$IMPL_PLAN"
      "$CATEG"
      "$CHG_SRC"
      "$RISK"
      "$NOW"
      "$NOW"
      "$CAB_REQUIRED"
      "$CAB_APPROVAL_GROUP"
      "$AFFECTED_CI_REQUIRED"
      "$SN_AFFECTED_CI")
    - echo $CHANGE_ID > CHANGE_ID.txt
    - request_approval "$SNOW_API_TOKEN" "$SN_ENV" "$CHANGE_ID"
    - email_approvers "$SNOW_API_TOKEN" "$SN_ENV" "$CHANGE_ID" "$CI_PIPELINE_URL"
  artifacts:
    when: on_success
    expire_in: 1 days
    paths:
      - CHANGE_ID.txt

Example extending `.create-change`

extending .deploy template for my-app

my-app-change-request:
  extends: .create-change
  only:
    changes: [ apps/app-platform-my-app/**/* ]
  when: manual
  needs: [ my-app-build-production, my-app-deploy-staging ]
  variables:
    SN_SYS_ID: "YOUR_SN_SYS_ID"
    SN_APP_NAME: "YOUR_SN_APP_NAME"
    SN_AFFECTED_CI: "YOUR_SN_AFFECTED_CI"
    SN_ENV: prod
    CAB_APPROVAL_GROUP: "YOUR_CAB_APPROVAL_GROUP"

`.await-approval`

Used to watch a change request for approval, for your deployment.

`.await-approval` Template

Await approval for change request if changes in master

.await-approval:
  stage: await-approval
  image:
    name: registry.gitlab.com/investec/docker/tooling/servicenow-tools:latest
  only:
    refs:
      - master
  variables:
    SN_ENV: staging
  script:
    - CHANGE_ID=$(cat CHANGE_ID.txt)
    - echo $CHANGE_ID > CHANGE_ID.txt
    - COMMIT_AUTHOR=$(./io-resources/scripts/get_commit_author.sh "$GITLAB_ACCESS_TOKEN" "$CI_PROJECT_ID" "$CI_COMMIT_SHA")
    - ./io-resources/scripts/await_approval.sh "$SNOW_API_TOKEN" "$SN_ENV" "$CHANGE_ID"  "$COMMIT_AUTHOR"
  artifacts:
    when: on_success
    expire_in: 1 days
    paths:
      - CHANGE_ID.txt

Example extending `.await-approval`

extending .deploy template for my-app

my-app-await-approval:
  extends: .await-approval
  only:
    changes: [ apps/YOUR-DIR-HERE/**/*, apps/YOUR-FILE-HERE.ts ]
  needs: [ my-app-change-request ]
  dependencies: [ my-app-change-request ]
  variables:
    TARGET_ENV: prod

`.review-change`

Used to review a change request, for your deployment.

`.review-change` Template

Review change request if changes in master

.review-change:
  stage: review-change
  image:
    name: registry.gitlab.com/investec/docker/tooling/servicenow-tools:latest
  only:
    refs:
      - master
  variables:
    SN_ENV: staging
  script:
    - CHANGE_ID=$(cat CHANGE_ID.txt)
    - echo $CHANGE_ID > CHANGE_ID.txt
    - ./io-resources/scripts/review_change.sh "$SNOW_API_TOKEN" "$SN_ENV" "$CHANGE_ID"
  artifacts:
    when: on_success
    expire_in: 1 days
    paths:
      - CHANGE_ID.txt

Example extending `.review-change`

extending .deploy template for my-app

my-app-review-change:
  extends: .review-change
  only:
    changes: [ apps/YOUR-DIR-HERE/**/*, apps/YOUR-FILE-HERE.ts ]
  needs: [ my-app-deploy-prod ]
  dependencies: [ my-app-deploy-prod ]
  variables:
    TARGET_ENV: prod

`.close-change`

Close change request if successful, for your deployment.

`.close-change` Template

Review change request if changes in master

.close-change:
  stage: close-change
  image:
    name: registry.gitlab.com/investec/docker/tooling/servicenow-tools:latest
  only:
    refs:
      - master
  when: manual
  variables:
    SN_ENV: staging
  script:
    - CHANGE_ID=$(cat CHANGE_ID.txt)
    - ./io-resources/scripts/close_change.sh "$SNOW_API_TOKEN" "$SN_ENV" "$CHANGE_ID"

Example extending `.review-change`

extending .deploy template for my-app

my-app-close-change:
  extends: .close-change
  only:
    changes: [ apps/YOUR-DIR-HERE/**/*, apps/YOUR-FILE-HERE.ts ]
  needs: [ my-app-review-change ]
  dependencies: [ my-app-review-change ]
  variables:
    TARGET_ENV: prod

.initiate​

.initiate Template​

Tip

Example extending .initiate​

.unit-test​

.unit-test Template​

Example extending .unit-test​

.build​

.build Template​

Example extending .build​

.deploy​

.deploy Template​

Example extending .deploy​

.create-change​

.create-change Template​

Example extending .create-change​

.await-approval​

.await-approval Template​

Example extending .await-approval​

.review-change​

.review-change Template​

Example extending .review-change​

.close-change​

.close-change Template​

Example extending .review-change​

`.initiate`

`.initiate` Template

Example extending `.initiate`

`.unit-test`

`.unit-test` Template

Example extending `.unit-test`

`.build`

`.build` Template

Example extending `.build`

`.deploy`

`.deploy` Template

Example extending `.deploy`

`.create-change`

`.create-change` Template

Example extending `.create-change`

`.await-approval`

`.await-approval` Template

Example extending `.await-approval`

`.review-change`

`.review-change` Template

Example extending `.review-change`

`.close-change`

`.close-change` Template

Example extending `.review-change`