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

# datree/policy

Use Datree's Policy Enforcement from within your build.
The orb includes several commands you can run during your build to enforce your policy.
For more information check here - https://docs.datree.io/docs/datree-and-circleci


## Commands

### branch-name-convention

Validate that the branch name is linked to your issue tracker.
This orb will fail your build in case the branch name doesn't contain the pattern expected by your issue tracker.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `issue_tracker` | enum | jira | Name of you issue tracker. Currently Jira and Pivotal are supported. |

### pull-request-title-convention

Validate that the pull request title is linked to your issue tracker.
This orb will fail your build in case the pull request title doesn't contain the pattern expected by your issue tracker.
In case the build doesn't run on a pull request, the orb will automatically continue.
For a 'how-to' guide on generating a Github Token see here - https://docs.datree.io/docs/generate-github-token.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `issue_tracker` | enum | jira | Name of you issue tracker - currently only Jira is supported. 
When using Pivotal, pull requests will connect automatically if the branch was linked.
 |
| `token` | string | $GITHUB_TOKEN | Enter either your github token or use the CircleCI UI to add your token under the 'GITHUB_TOKEN' environment variable |

### version-alignment

Control version alignment of packages across multiple repositories.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `API_KEY` | string | $DATREE_API_KEY | Enter either your Datree api key or use the CircleCI UI to add your token under the 'DATREE_API_KEY' env var |
| `file_path` | string |  | JSON formatted object including the expected an actual code component version. For more information view README file |
| `payload` | string |  | JSON formatted object including the expected an actual code component version. For more information view README file |

## Examples

### branch-name-convention

Example of using Datree's branch name convention rule.
The `issue_tracker` parameter is optional (defaults to Jira)


```yaml
orbs:
  datree: datree/policy@volatile
description: A circle-ci job to enforce Datree's branch name convention rule
jobs:
  my_job:
    docker:
      - image: circleci/node:10
    steps:
      - datree/branch-name-convention:
          issue_tracker: jira
version: 2.1
workflows:
  main:
    jobs:
      - my_job
```

### pull-request-title-convention

Example of using Datree's pull request title convention rule.
The `issue_tracker` parameter is optional (defaults to Jira).
The `token` parameter is required. It is possible to pass it using `GITHUB_TOKEN` environment variable.


```yaml
orbs:
  datree: datree/policy@volatile
description: A circle-ci job to enforce Datree's pull request title convention rule
jobs:
  my_job:
    docker:
      - image: circleci/node:10
    steps:
      - datree/pull-request-title-convention:
          issue_tracker: jira
version: 2.1
workflows:
  main:
    jobs:
      - my_job:
          context: github-token-context
```

### version-alignment

Example of using Datree's version alignment rule.
The `payload` parameter is required. In this example we run a fake job that extracts the actual installed versions from within the build.
The `DATREE_API_KEY` parameter is required. It is possible to pass it using an environment variable of the same name.


```yaml
orbs:
  datree: datree/policy@volatile
description: A circle-ci to enforce uses Datree's version alignment rule
jobs:
  extract-versions:
    docker:
      - image: circleci/circleci-cli:0.1.2709
    steps:
      - run: echo "running version extraction script"
  my_job:
    docker:
      - image: circleci/node:10
    steps:
      - datree/version-alignment
version: 2.1
workflows:
  main:
    jobs:
      - extract-versions
      - my_job:
          requires:
            - extract-versions
          context: datree-api-context
          payload: >-
            { "expected": 
            [{"name":"webpack-node-externals","category":"npm","version":"1.7.2"}],
            "actual":
            [{"name":"webpack-node-externals","category":"npm","version":"1.7.2"}]
            }
```