# CircleCI

### How to integrate Meterian with CircleCI pipeline

Adding Meterian to your CI pipeline is very simple, and it does not require much effort:

 Here is a simple config.yml configuration file that does so:

```
version: 2.1

orbs:
  docker: circleci/docker@0.5.20
jobs:
  meterian:
    machine: true
    steps:
      - checkout
      - run: |
            docker run --rm \
            --volume ${PWD}:/workspace --env METERIAN_API_TOKEN=$METERIAN_API_TOKEN \
            meterian/cli [Meterian CLI Options]
workflows:
  version: 2
  commit-workflow:
    jobs:
      - meterian
```

Then on the CircleCI dashboard, open your project and open your project' settings.\
Here you will be able to set the METERIAN\_API\_TOKEN as environment variable.

{% hint style="info" %}
To retrieve a Meterian API Token visit the [Meterian Dashboard](https://www.meterian.com/account); in your account select the tab "Tokens" and create a new one, or use an existing one.

API tokens are available only on paid account. To upgrade your subscription, please [contact us](mailto:support@meterian.io).
{% endhint %}

Once the configuration has been committed and pushed on the repository, CircleCI will launch the 'meterian' job.

Learn more about the Meterian Client [here](https://docs.meterian.io/the-client/client).

### How does it work

The above example uses the CircleCI machine executor which checks out your project's source code and runs the latest tag of the [Meterian Docker image](https://docs.meterian.io/the-meterian-client-dockerized) against it through Docker. This image contains the latest version of the Meterian client and the building tools for all the languages we support. Running it ensures that a scan of your project is performed yielding results that will either cause the CircleCI task to pass or fail breaking the workflow.

### Docker executor

Should you wish to use the Docker executor here's an adaptation of the above example that does just that

```
version: 2.1

jobs:
  meterian-scan:
    docker:
    - image: meterian/cli:latest
    working_directory: /workspace
    steps:
      - checkout
      - run: /root/circleci_entrypoint.sh
  
workflows:
  version: 2
  commit-workflow:
    jobs:
      - meterian-scan
```

Jobs that use the Docker executor run within a container created with the specified image (in this case we are using the Meterian Dockerized Client image), hence why you need to invoke the entry point script yourself as part of your steps to have your project scanned (after the source code checkout on line 7 of the snippet). 

The `circleci_entrypoint.sh` script at line 8 is a tailored script designed for these type of jobs covering aspects such as needing SSH access for the scan. An example of a scan that might need this is the one involving a Golang project. Assuming that the project defines modules that live on private repositories only accessible through a pair of SSH keys teaming the latter script with CircleCI's [`add_ssh_keys`](https://circleci.com/docs/2.0/configuration-reference/#addsshkeys) special step will allow you to easily tackle that. 

Here's an adapted example suited to scan a Golang project winch will require private modules to be resolved

```
version: 2.1

jobs:
  meterian-scan:
    docker:
    - image: meterian/cli:latest
    working_directory: /workspace
    steps:
      - checkout
      - add_ssh_keys:
          fingerprints:
            - "SO:ME:FIN:G:ER:PR:IN:T"
      - run: |
            git config --global url.ssh://git@github.com/.insteadOf https://github.com/
            export GOPRIVATE=PRIVATE_REPOS_GLOB_PATTERNS
            /root/circleci_entrypoint.sh

workflows:
  version: 2
  commit-workflow:
    jobs:
      - meterian-scan
```

[After adding SSH keys in the job](https://circleci.com/docs/2.0/add-ssh-key/), GIT and GO are configured to download non-public code. The configurations are then appropriately propagated to the Meterian client for the scan that will follow thanks to our tailored script.

Learn more about configuring GO for downloading non-public code [here](https://pkg.go.dev/cmd/go#hdr-Configuration_for_downloading_non_public_code).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.meterian.io/ci-server-integrations/circle-ci.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.