# Concourse CI

**Integrate Meterian with Concourse CI pipeline**

Assuming you have a working instance of Concourse CI, integrating Meterian only involves a few simple steps. These consist of a secrets pre-configuration to ensure the scan is authenticated and the addition of a task to a pipeline to execute said scan.

**Secrets pre-configuration**

In a `.yml` file set the key `METERIAN_API_TOKEN` as it follows

```
# secrets.yml
METERIAN_API_TOKEN: your API token
```

{% 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 %}

**Meterian scan pipeline task**

Now prepare a pipeline where the codebase you intend to scan is firstly pulled as a resource and then scanned by the Meterian client (to learn more about the pipeline syntax please refer to the [official documentation](https://concourse-ci.org/pipelines.html))

```
# pipeline.yml
resources:
- name: source-code
  type: git
  source:
    uri: your repository uri
    branch: the target branch

jobs:
- name: you-job-name
  plan:
  - get: source-code
    trigger: true
  - task: meterian-scan
    config:
      platform: linux
      image_resource:
        type: registry-image
        source: 
          repository: meterian/cli
      inputs:
        - name: source-code
          path: .
      run: 
        path: /root/concourse.sh
        args: [ comma-separated arguments for the client ]
      params:
        METERIAN_API_TOKEN: ((METERIAN_API_TOKEN))
```

In case of an on-premise instance of Meterian you also will need to specify the following  params

```
CLIENT_ENV: your site environment (e.g. www.meterian.io -> www )
CLIENT_PROTO: your site protocol 
CLIENT_DOMAIN: your site domain (e.g. www.meterian.io -> meterian.io )
```

Once done run the following [fly client](https://concourse-ci.org/fly.html) command to apply this pipeline to your Concourse CI instance

```
$ fly -t <Concourse target name> \
  set-pipeline -p <pipeline name> \
  -c pipeline.yml \
  -l secrets.yml
```

This example triggers a build whenever your repository is updated on GitHub. The repository is treated as a [git-resource](https://github.com/concourse/git-resource) resource arbitrary named "source-code". Note there are countless resources developed by the Concourse CI community so consider consulting their [catalog](https://resource-types.concourse-ci.org/) for other alternatives.

**Adjustments for private repositories**

The above example works great with public repositories but in order to use private repositories the pipeline requires some minor tweaks.&#x20;

If you haven't already, create and set up deploy keys for your private repository following [this guide](https://docs.github.com/en/developers/overview/managing-deploy-keys#deploy-keys).

Refer to the resource object and update your repository `uri` to a git ssh clone uri and add your deploy private key through the `private_key` attribute as it follows

```
resources:
- name: source-code
  type: git
  source:
    uri: git@github.com:...
    branch: main
    private_key: ((private-key))
```

Now apply the changes through the fly client binding your private key to the variable `private-key`

```
$ fly -t <Concourse target name> \
  set-pipeline -p <pipeline name> \
  -c pipeline.yml \
  -l secrets.yml \
  -v private-key="$(cat /path/to/your/private/key)"
```

**Caveats**

As of now the `git-resource` [always pulls the specified branch in detached mode](https://github.com/concourse/git-resource/pull/257) causing the scan to report a misleading branch name unless the appropriate override is provided. To fix this issue provide the `--project-branch` arguments with the right branch name to the Meterian scan task

```
  - task: meterian-scan
    config:
      platform: linux
      image_resource:
        type: registry-image
        source: 
          repository: meterian/cli
      inputs:
        - name: source-code
          path: .
      run: 
        path: /root/entrypoint.sh
        args:  [ --project-branch=correct-branch-name ]
      params:
        METERIAN_API_TOKEN: ((METERIAN_API_TOKEN))
```

A full list of available client arguments can be found here <https://docs.meterian.io/the-client/command-line-parameters>