> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# apollo/internal-platform-orb

Helpful utilities we use inside Apollo GraphQL


## Commands

### checksum-directory

Build checksum of all folders in `root`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `root` | string | . |  |
| `to` | string | DIRSUM |  |

### circleci-check-pipeline-size

Processes the given config in an attempt to see if it is larger than allowed by Circle

| Parameter | Type | Default | Description |
|---|---|---|---|
| `circleci-token-environment-variable` | string |  |  |
| `org-slug` | string |  | vsc provider plus org name. Example github/apollographql |
| `pipeline-file-path` | string |  |  |

### circleci-long-running-workflows

for any job that is old, cancel it and warn the people. Must run the setup command on each new executor.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `cancel` | boolean | false | Whether or not to cancel old Workflows which are found. |
| `circleci-token-variable` | string | CIRCLECI_TOKEN | the name of the environmental variable that contains the circleci token |
| `ignore-when-all-on-hold-job-names-contain` | string |  | Do not warn about workflows where all of the on hold job names contain this string (also supported - comma seperated list) |
| `org-repo-slug` | string |  | github-username-or-org-name/repo-name |
| `output` | string | /tmp/circleci-long-running-workflows.tsv | Location at which to place tsv value file. |
| `window-end-in-hours` | integer | 0 | Number of hours ago to end search window based on Worflow's `created_at` date. |
| `window-start-in-hours` | integer | 0 | Number of hours ago to start search window based on Worflow's `created_at` date. |

### circleci-stop-if

Helper command which will `halt` the entire execution of the running `job` if the value of `value` parameter is the value of the `stop-if-value-is` parameter.
Circle's "when" conditions are great, but you could use this as a pre-step in a workflow to avoid executing a job

| Parameter | Type | Default | Description |
|---|---|---|---|
| `stop-if-value-is` | string |  | If the value parameter matches this value, halt job execution. Job will still be green, but further steps will not happen |
| `value` | string |  | A value - maybe even a Circle parameter - to check |

### circleci-stop-if-not

Helper command which, like circleci-stop-if will `halt` the entire execution of the running `job`, but does so if the value of `value` parameter is NOT the value of the `continue-if-value-is` parameter.
Circle's "when" conditions are great, but you could use this as a pre-step in a workflow to avoid executing a job

| Parameter | Type | Default | Description |
|---|---|---|---|
| `continue-if-value-is` | string |  | If the value parameter matches this value, halt job execution. Job will still be green, but further steps will not happen |
| `value` | string |  | A value - maybe even a Circle parameter - to check |

### circleci-stop-if-not-pr

Helper command which will `halt` the entire execution of the running `job` if the job is running on a branch without a PR.
Circle's "when" conditions are great, but you could use this as a pre-step in a workflow to avoid executing a job

| Parameter | Type | Default | Description |
|---|---|---|---|
| `do-when` | string | on_success | Value passed to "when" parameter on job. Useful to let job run even after a prior step failed |

### enrich-mustache

When dealing with large dynamic pipelines we found Circle's built in functionality (when statements etc) somewhat limiting. What if we wanted to run the same workflow multiple times, with different values, without repeating ourselves (especially useful in a monorepo with multiple microservices!)?
We realized the easiest way forward was to preprocess our Circle config files with a pre-processing language, one we could feed a JSON values file into (like Circle's own continuation plugin!) where the keys in the JSON file are treated as variables to render the output with.
To accomplish this task we landed on the mustache template language, given its longevity in the community. Mustache templates can be rendered and used by other parts of the CircleCI infrastructure, see enrich-mustache-folder for an example which was made to support folders of mustache templates (ie in fyaml format) that need to be rendered then packed.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `json-data-file-path` | string |  | all the keys in this JSON file are made availible as variables in your mustache code. Yes, even arrays |
| `output-file-path` | string |  | Where the rendered file should go |
| `template-file-path` | string |  | The file to run through mustache |

### enrich-mustache-folder

Meant as a wrapper if you're using enrich-mustache with a folder full of fyaml. Must run setup command first.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `install-cci-cli` | enum | true | will install the CircleCI cli (required) |
| `json-data-file-path` | string |  |  |
| `output-file-path` | string |  | where you want the packed file to be |
| `output-folder-path` | string |  | destination folder. This command will create folders your Circle fyaml expects |
| `template-folder-path` | string |  | the path to your fyaml folder. Should include the folder name (ie config.fyaml) |

### gcp-authorize

Authorize GCP from the contents of an environmental variable with optional base64 decoding step. You must have installed the gcloud command line tool yourself, previously. This is a slightly enhanced version of the gcp-cli orb's authorize command

| Parameter | Type | Default | Description |
|---|---|---|---|
| `delete-cred-file` | enum | true | delete the credentials file |
| `do-activate-service-account` | enum |  | This is a service account that should be authed |
| `do-docker-login` | enum |  | Have Docker use these creds to log into Google Artifact Registry, where we have a Docker registry. Likely will need to run setup_remote_docker command first.  |
| `do-helm-login` | enum |  | Have Helm use these creds to log into Google Artifact Registry, using Helm's support for OCI registries. |
| `environment-variable-name` | string | GCLOUD_SERVICE_ACCOUNT | the value of this specified environment variable contains the key, either in base64 or just JSON (we'll figure it out) |

### gcp-oidc-authorize

Authorize the GCP CLI using OIDC rather than receiving a service account's credentials via environment variable. This command creates an ephemeral GCP session by leveraging GCP Workload Identity. Workload Identity must be configured in the project you are attempting to authenticate to prior to using this command. Additionally, you will need to have installed the gcloud command line utility in your CI execution environment prior to using this command. This is a enhanced version of the gcp-cli orb's authorize command.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `delete-cred-file` | enum | false | delete the credentials file |
| `do-activate-application-default-creds` | enum | true | Configure the environment to use the retrieved credentials as the Application Default Creds (ADC). This option does not work if delete-cred-file is true |
| `do-docker-login` | enum |  | Have Docker use the retrieved creds to log into Google Artifact Registry, where we have a Docker registry. Likely will need to run setup_remote_docker command first. |
| `do-helm-login` | enum |  | Have Helm use the retrieved creds to log into Google Artifact Registry, using Helm's support for OCI registries. |
| `docker-registry-url` | string | us-central1-docker.pkg.dev,gcr.io | A comma-separated list of Docker registries to which  this command should authenticate. This command configures authentication credentials via the GCloud CLI, so these will need to be hosted in GCP Artifact Registry. Only used if do-docker-login is true. |
| `gcp-cred-config-file-path` | string | /tmp/circleci-gcp_cred_config.json | The full path to the file used to store GCP OIDC Authentication configuration. This is an internal value and should only be changed if the default file conflicts with your needs |
| `helm-registry-url` | string | https://us-central1-docker.pkg.dev | The URL of the Helm Registry to which this command should authenticate. This command configures authentication credentials via the GCloud CLI, so this Helm Registry will need to be hosted in GCP Artifact Registry. Only used if do-helm-login is true. |
| `oidc-token-file-path` | string | /tmp/circleci-oidc_token.json | The full path to the file used to store the CCI-provided OIDC token. This is an internal value and should only be changed if the default file conflicts with your needs |
| `project-id` | env_var_name | GCP_PROJECT_ID | The name of the environment variable containing the GCP project ID to be authenticated to. For example, the named variable could contain "myproject-123456" |
| `service-account-email` | env_var_name | GCP_SERVICE_ACCOUNT_EMAIL | The name of the environment variable containing the service account email to use to authenticate to GCP |
| `workload-identity-pool-id` | env_var_name | GCP_WIP_ID | The name of the environment variable containing the workload identity pool to use to authenticate to GCP |
| `workload-identity-pool-provider-id` | env_var_name | GCP_WIP_PROVIDER_ID | The name of the environment variable containing the workload identity pool provider to use to authenticate to GCP |

### git-diff-set-parameters

This command outputs a JSON file where matching regex entries output their appropriate keys and values. This does the heavy lifting for the enrich-mustache-from-path-file job, see that job for documentation

| Parameter | Type | Default | Description |
|---|---|---|---|
| `all-mappings-match-if-config-path-changed` | enum |  |  |
| `base-revision` | string |  | Compare this branch to its ancestor named |
| `config-path` | string |  |  |
| `mapping` | string |  |  |

### github-auth

Authorize Github. Run this before any other github- command in this orb. Pulls Github personal token from GH_BOT_KEY_B64 environment variable (in base64 encoded...)


| Parameter | Type | Default | Description |
|---|---|---|---|
| `do-when` | string | on_success | Value passed to "when" parameter on job. Useful to let job run even after a prior step failed |

### github-bot-comment-on-pr

This command takes FILE_RESULTS, formats it for Markdown, then adds it to the current PR. MUST be used with the github-orb context


| Parameter | Type | Default | Description |
|---|---|---|---|
| `bot-making-comments` | string |  | name of the bot making all these comments |
| `command` | string |  | A command which must produce a /tmp/notification.txt file. If no, or empty file, produced step is halted. The command optionally may produce a /tmp/report.md file, which will be linked as a secret gist, designed to give an optional level of detail to your users. |
| `do-when` | string | on_success | Value passed to "when" parameter on job. Useful to let job run even after a prior step failed |
| `overlarge-content-to` | enum | print | If the total size of /tmp/notification.txt is larger than Github Pull Request comment limits, instead output the content to this location. |
| `title` | string |  |  |
| `update-last` | boolean | false | Update the last comment from this bot with this title instead of creating a new one |

### github-bot-delete-bot-comments

Finds any previous comments made by this bot, with a given header, on the current PR, and deletes them.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `bot-making-comments` | string |  | name of the bot making all these comments |
| `do-when` | string | on_success | Value passed to "when" parameter on job. Useful to let job run even after a prior step failed |
| `really-delete-comments` | boolean | true |  |
| `skip-last` | boolean | false | if true, delete every comment except the last one |
| `title` | string |  | delete comments that start with this header |

### proceed-if-changes

Helper command which will `halt` the the entire execution of the running `job` when no changes are found underneath the specified path. ie, ONLY "proceed if there are changes".
Very useful for instances such as looking through Terraform output which says that running `apply` will result in nothing happening in remote because "no changes present".


| Parameter | Type | Default | Description |
|---|---|---|---|
| `changes-iregex` | string |  | If present, looks for a line which indicates that the file being searched has changes. ie, no match means there are _no_ changes. |
| `name-filter` | string |  | Filter for pruning files underneath `path`. Will look at the full path (ie you might want to prefix your names with .*) |
| `no-changes-iregex` | string |  | If present, looks for a line which indicates that the file being searched has no changes. ie, no match means there _are_ changes. |
| `path` | string |  | Absolute path underneath which one will look for changes. |

### setup

Downloads the original repository, for helper scripts

| Parameter | Type | Default | Description |
|---|---|---|---|
| `download-reference` | string | main | tag number OR URL encoded string |

### slack-circleci-build

Alert slack with a message geared towards CircleCI builds, including necessary user, and links.
NOTE: Must be run with the slack-orb context


| Parameter | Type | Default | Description |
|---|---|---|---|
| `channel` | string |  | The name of the channel you want to post to. Can also be set by exporting "export CHANNEL=<...> >> $BASH_ENV" |
| `continue_on_failure` | boolean | false | Whether to continue execution even if this step fails |
| `emoji` | string |  | Textual reference for a prefixed emoji to be formatted into the message to Slack. |
| `fail` | string |  | Markdown enabled text to be placed in the failure message to Slack. |
| `link` | string | https://app.circleci.com/pipelines/workflows/$CIRCLE_WORKFLOW_ID |  |
| `notify` | string |  | Markdown enabled text to be placed in the message to Slack. |
| `who-did-it` | string | gh:$CIRCLE_USERNAME | Who did the action |

### slack-circleci-build-compact

Alert slack with a custom message on pass or fail.
NOTES: - Must be run with the slack-orb context - Must be run on a system with JQ and Curl installed


| Parameter | Type | Default | Description |
|---|---|---|---|
| `channel` | string |  | The name of the SINGLE channel you want to post to. |
| `fail` | string |  | Markdown enabled text to be placed in the failure message to Slack.
 |
| `pass` | string |  | Markdown enabled text to be placed in the failure message to Slack.
 |

### slack-from-command

Post a Slack message where the message content is from running a command. That command MUST output /tmp/notification.txt. If no (or blank) file execution is halted
NOTE: Must be run with the slack-orb context


| Parameter | Type | Default | Description |
|---|---|---|---|
| `channel` | string |  | The name of the channel you want to post to. Can also be set by exporting "export CHANNEL=<...> >> $BASH_ENV" |
| `command` | string |  | A command which must produce a /tmp/notification.txt file |
| `continue_on_failure` | boolean | false | Whether to continue execution even if this step fails |

### slack-notify-compact

Blatant slimmed down version of the traditional Slack Orb's `notify` command.
https://github.com/CircleCI-Public/slack-orb/blob/master/src/commands/notify.yml
The regular `notify` command comes in at a whopping 12K for processed config size _every_ time you call it or reference it. This version aims to be far more lightweight, but _will not_ hold your hand. If you need more features, use the regular Orb. If you are having trouble debugging, use the regular Orb.
All parameters, env vars, and spiritual influences herein will follow the regular Orb _heavily_.
NOTES: - Must be run with the slack-orb context - Must be run on a system with JQ and Curl installed


| Parameter | Type | Default | Description |
|---|---|---|---|
| `channel` | string |  | The name of the SINGLE channel you want to post to. |
| `continue_on_failure` | boolean | false | Whether to continue execution even if this step fails |
| `custom` | string |  | Enter a custom message template.
1. Create your message template using the Block Kit Builder: https://app.slack.com/block-kit-builder/.
2. Insert any desired environment variables.
3. Paste value here.
 |
| `event` | enum | always | In what event should this message send? Options: ["fail", "pass", "always"]
 |

### terraform-terragrunt-check-formatting

| Parameter | Type | Default | Description |
|---|---|---|---|
| `check-terraform` | boolean | true |  |
| `check-terragrunt` | boolean | true |  |
| `working-directory` | string | /code |  |

### terraform-tflint-all

For every directory that has a .tf file, run tflint. Assumes tflint is installed in your executor

| Parameter | Type | Default | Description |
|---|---|---|---|
| `check-directories` | string |  | Which directories to check, seperated by space |
| `working-directory` | string | /code/ |  |

## Jobs

### alert-github

Alert github with an updatable comment. Will continually purge and replace comments based on their parameters.title. NOTE: Must be paired with the github-orb context


| Parameter | Type | Default | Description |
|---|---|---|---|
| `bot-making-comments` | string |  | name of the bot making comments |
| `changes-iregex` | string |  | `changes-iregex` parameter to be passed to `proceed-if-changes` |
| `delete-bot-comments` | boolean | true | Delete comments previously made by the delete-bot-comments bot |
| `name-filter` | string |  | `name-filter` parameter to be passed to `proceed-if-changes` |
| `no-changes-iregex` | string |  | `no-changes-iregex` parameter to be passed to `proceed-if-changes` |
| `notification-command` | string |  | Bash command which will be run to generate the markdown payload to comment on the PR in Github. Command must send desired output to /tmp/notification.txt OR may send output to /tmp/report.md, which will be used to create a secret gist. |
| `overlarge-content-to` | enum | print |  |
| `path` | string |  | `path` parameter to be passed to `proceed-if-changes` |
| `title` | string |  | Title to be given to this PR comment in Github. |
| `update-last` | boolean | false | Update the last comment from this bot with this title instead of creating a new one |
| `workspace` | string | /tmp/workspace | `workspace` parameter to attach. |

### alert-slack

Alert slack with an notification.
Can be paired with parameters for proceed-if-changes to prevent sending if there are no updates.
NOTE: Must be paired with the slack-orb context


| Parameter | Type | Default | Description |
|---|---|---|---|
| `changes-iregex` | string |  | `changes-iregex` parameter to be passed to `proceed-if-changes` |
| `channel` | string |  | The name of the channel you want to post to. |
| `continue_on_failure` | boolean | false | Whether to continue execution even if this job fails |
| `emoji` | string |  | Textual reference for a prefixed emoji to be formatted into the message to Slack. |
| `fail` | string |  | Markdown enabled text to be placed in the failure message to Slack. |
| `name-filter` | string |  | `name-filter` parameter to be passed to `proceed-if-changes` |
| `no-changes-iregex` | string |  | `no-changes-iregex` parameter to be passed to `proceed-if-changes` |
| `notify` | string |  | Markdown enabled text to be placed in the message to Slack. |
| `path` | string |  | `path` parameter to be passed to `proceed-if-changes` |
| `workspace` | string | /tmp/workspace | `workspace` parameter to attach. |

### alert-slack-from-command

Alert slack with an notification.
Can be paired with parameters for proceed-if-changes to prevent sending if there are no updates.
NOTE: Must be paired with the slack-orb context


| Parameter | Type | Default | Description |
|---|---|---|---|
| `channel` | string |  | The name of the channel you want to post to. |
| `command` | string |  | A command which must produce a /tmp/notification.txt file |
| `continue_on_failure` | boolean | false | Whether to continue execution even if this job fails |
| `workspace` | string | /tmp/workspace | `workspace` parameter to attach. |

### enrich-mustache-from-path-filter

Meant to be a drop in replacement for Circle's path-filtering/filter, to be used in a situation where:
  * you want an easy way to use the rest of this orb's enhance-mustache functionality
  * find that Circle's official path-filtering orb doesn't work for your use case anymore.

Circle's path-filtering works great if you want to turn on or off currently defined workflows or part of a pipeline. But if you have a situation where you want to create many instances of the SAME jobs, this is much harder to keep DRY.
In enrich-mustache-from-path-filter instead of passing parameters via CircleCI continutation pipeline, it renders the specified Circle pipeline as a mustache document. This Circle job was created to make the path from path-filter
Rules for parameters provided in the mappings section:
  1. these must be JSON literals
  2. If the JSON literal is an array [], if multiple matches are
     found then all the matched values will be concatinated in an array
  3. If a value is not marked as an array then subsequent sets will override

| Parameter | Type | Default | Description |
|---|---|---|---|
| `all-mappings-match-if-config-path-changed` | enum |  | If true, then if the file in config-path changed, treat all mappings as if they match |
| `base-revision` | string | main | Compare this branch to its ancestor named |
| `config-path` | string |  | Location of the (mustache enriched) config file |
| `mapping` | string |  | Like path-filtering, the format is:
  REGEX PARAMETER VALUE

  (space seperated values)

  For each line provided the results of git diff --name-only
  is examined for matches. This uses PCRE style regex, as defined in Python3

  the output of git diff $YOUR_BASE_REVISION_PARAMETER head is checked to
  see if matches REGEX. If it does the mustache parameter PARAMETER will be
  created, and given VALUE. (In Circle's path-filtering orb this sets pipeline parameters).

  VALUE must be a JSON literal. For example: true, "hello", 2. NOTE: You must include quotes.

  enrich-mustache-from-path-filter adds to this syntax in supporting appendable arrays.
  Given two mapping lines
  folder-one/.* build-what ["one"]
  folder-two/.* build-what ["two"]

  if BOTH folder-one and folder-two have changed files the value of the build-what variable will be ["one", "two"].

  This is special casing for arrays only. Scalar types will have
  path-filtering behavior: given two matches the last one wins.
  Which is the last one? Potentially undefined behavior.

  The resulting output will be written to /tmp/enrich-parameters.json |
| `pre-process-command` | string |  | allows you to insert a command after set-parameters has generated a JSON file. Useful for post-processing same (ie with jq's + command) |

## Executors

### default

Executors


| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | lts | Pick a specific cimg/node image variant: https://hub.docker.com/r/cimg/node/tags
 |

## Examples

### deployment-notifications

See how to use our Slack notification job.


```yaml
version: '2.1'
orbs:
  apollo-platform-oss-orb: apollo/internal-platform-orb@1.0.6
jobs:
  build-and-deploy-it:
    docker:
      - image: cimg/openjdk:17.0.3
    steps:
      - run:
          command: echo 'I would build something'
      - run:
          command: echo 'and I would deploy it'
workflows:
  use-my-orb-to-build-then-alert-slack:
    jobs:
      - build-and-deploy-it
      - apollo-platform-oss-orb/alert-slack:
          channel: build-alerts
          context:
            - slack-orb
          emoji: ':checkered_flag:'
          fail: '*failed build* of app:my-example'
          name: Alert Slack about build!
          notify: '*finished build* of app:my-example'
          requires:
            - build-and-deploy-it
```

### enrich-mustache-from-path-filter-job

Our enrich-mustache-from-path-filter is meant to be a drop in replacement for path-filtering/filter BUT: meant to be used in a situation where EITHER you want an easy way to use the rest of this orb's enhance-mustache functionality OR find that Circle's official path-filtering orb doesn't work for your use case anymore.
For example, Circle's path-filtering works great if you want to turn on or off currently defined workflows or part of a pipeline. But if you have a situation where you want to create many instances of the SAME jobs, this is much harder to keep DRY.
If, for example, you have a dynamic configuration and for each folder modified you want to do the same job, but with different parameters depending on what folder.
For example, you always want to do `gradle`, but sometimes you want to do gradle build microservice-a and sometimes you want to do gradle build microservice-b.
Now, with path-filtering you would need to set up indidivdual pipeline parameters for each case and define seperate parts of the workflow, running using when statements. Except these workflows or jobs are almost always the same - you're just always running gradle!
Instead, create a mustache template and let this job generate a pipeline based on the mustache variables your MAPPING block defines.
If multiple mapping files match AND the last item is a JSON array, multiple matches will append. (Normal JSON scalars will overwrite in an undefined way).
The following example depends on .circleci/continue-config.yml looking like so
version: 2.1 workflows:
  build-it:
    jobs:
      - do-gradle:
          task: "{{what-gradle-action}}"
      {{#build-docs}}
      - do-build-docs:
          name: {{.}}
      {{/build-docs}}


```yaml
version: '2.1'
setup: true
orbs:
  apollo-internal-platform-orb: apollo/internal-platform-orb@1.0.1
workflows:
  launch-jobs:
    jobs:
      - apollo-internal-platform-orb/enrich-mustache-from-path-filter:
          base-revision: main
          config-path: .circleci/continue-config.yml
          mapping: |
            microservice-a/.* what-gradle-action ":a:build"
            microservice-b/.* what-gradle-action ":b:build"
            docs-a/.* build-docs ["a"]
            docs-a/.* build-docs ["b"]
```

### example

Sample example description.


```yaml
version: '2.1'
orbs:
  <orb-name>: <namespace>/<orb-name>@1.2.3
workflows:
  use-my-orb:
    jobs:
      - <orb-name>/<job-name>
```