---
url: /en/build/file-reference.md
description: >
  Explains the four types of file references supported in CNB pipeline
  configurations (pipeline templates, environment variable imports, built-in
  task parameters, plugin task parameters), including permission controls to
  prevent information leakage.
---
## Background

Pipeline configuration files can reference other files for pipeline templates,
environment variables, task parameters, etc.

Referenced files may contain sensitive information,
so permission checks are needed to prevent information leakage.

## Reference Methods

CNB supports four types of configuration file references:

* Pipeline template reference: [include](./grammar.md#include)
* Environment variable reference: [imports](./grammar.md#pipeline-imports)
* Built-in task parameter reference: [optionsFrom](./grammar.md#job-optionsfrom)
* Plugin task parameter reference: [settingsFrom](./grammar.md#job-settingsfrom)

**Note:**

File paths declared in `imports`, `optionsFrom` and `settingsFrom` support environment variables.

```yaml title=".cnb.yml"
main:
  push:
    - env:
        CNB_CONFIG_URL: https://cnbprod.alpha.qq.com/<your-repo-slug>/-/blob/main/xxx
        CNB_CONFIG_FILE: account.yml
        CNB_ENV_FILE_URL: https://cnbprod.alpha.qq.com/<your-repo-slug>/-/blob/main/xxx
      imports:
        - https://cnbprod.alpha.qq.com/<your-repo-slug>/-/blob/main/xxx/env1.yml
        - ${CNB_ENV_FILE_URL}/env2.yml
      stages:
        - name: echo
          script: echo 1
```

`optionsFrom` and `settingsFrom` also support environment variables:

```yaml title=".cnb.yml"
main:
  push:
    - env:
        CNB_CONFIG_URL: https://cnbprod.alpha.qq.com/<your-repo-slug>/-/blob/main/xxx
        CNB_CONFIG_FILE: account.yml
      stages:
        - name: Built-in task
          type: some-type
          optionsFrom:
            - ${CNB_CONFIG_URL}/${CNB_CONFIG_FILE}
        - name: Plugin task
          image: some-image
          settingsFrom:
            - ${CNB_CONFIG_URL}/${CNB_CONFIG_FILE}
```

Additionally, `optionsFrom` and `settingsFrom` support reading local files.
Even if `./path/to/file` doesn't exist in the repository,
you can write it in the pipeline for loading during execution. Replace the remote paths with local ones:

```yaml title=".cnb.yml"
# Replace remote paths with local ones, rest unchanged
main:
  push:
    - stages:
        - name: Write config
          script: echo some-content > ./path/to/file-not-in-git
        - name: Built-in task
          type: some-type
          optionsFrom:
            - ./path/to/file-not-in-git
        - name: Plugin task
          image: some-image
          settingsFrom:
            - ./path/to/file-in-git
```

## Permission Checks

For configuration files in public or same-origin repositories, pipelines can reference them directly.

For private and non-origin repositories, you can declare four fields: `allow_slugs`,
`allow_events`, `allow_branches`, and `allow_images` to control the access scope.
All four fields support `glob` pattern strings (multiple expressions separated by `,` or `|`) or string arrays.

::: tip Glob Matching Rules

* `*` matches any character **except** `/`. For example:
  `my-group/*` matches `my-group/repo` but not `my-group/sub/repo`.
* `**` matches any character **including** `/`. For example:
  `my-group/**` matches both `my-group/repo` and `my-group/sub/repo`.

Use `**` when you need to match paths containing `/` (e.g., repositories under nested groups).
:::

For example:

```yaml
allow_slugs: "group/project,some/another-project/feature-*"
allow_events:
  - push
  - tag_push
  - "tag_deploy.*"
allow_images: "cnbcool/ssh"
allow_branches:
  - main
  - "feature/*"
```

It is recommended to declare multiple expressions using string arrays for better readability.
If the configuration file is in a text format that does not support arrays, use the string format.

If the above four fields are not declared,
it checks whether the pipeline trigger is a `developer` or higher in the target repository.
If yes, access is granted; otherwise, access is denied.

Where:

* `allow_slugs`: specifies which repositories' pipelines are allowed to read the current file.
* `allow_events`: specifies under which events pipelines can read the current file.
  Configurable event names refer to [Trigger Events](./trigger-rule.md#trigger-event).
* `allow_branches`: specifies under which branches pipelines can read the current file.
* `allow_images`: specifies which image plugins are allowed to read the current file.

The permission check flow for whether a pipeline can load target files is shown below:

```mermaid
flowchart LR
    subgraph allow checks
      slug-check --> branch-check --> image-check --> event-check
    end
    subgraph allow necessity checks
      allow_events-necessity-check --> allow_images-necessity-check
    end
    start([Start]) --> public-repo{Public repo?}
    public-repo --Yes--> Can-access
    public-repo --No--> same-source{Same-source?}
    same-source --Yes--> Can-access
    same-source --No--> allow-necessity-check[Allow necessity check]
    allow-necessity-check --> necessity-check-passed{Check passed?}
    necessity-check-passed -- Yes --> allow-declared{Allow declared?}
    necessity-check-passed -- No --> Cannot-access
    allow-declared -- No --> has-file-read-permission{File read permission?}
    allow-declared -- Yes --> allow-check[Allow check]
    has-file-read-permission --Yes--> Can-access
    has-file-read-permission --No--> Cannot-access
    allow-check --> allow-check-passed{Check passed?}
    allow-check-passed --Yes--> Can-access
    allow-check-passed --No--> Cannot-access
```

Flow explanation:

* Same source: Pipeline and target file belong to same repository
* Allow check: Declared allow fields checked sequentially, all must pass
* File read permission: See [Role Permissions](../guide/role-permissions.md)

```mermaid
flowchart LR
  strat([Allow necessity check]) --> untrusted-event{Untrusted event?}
    untrusted-event --No--> image-task{Image task?}
    untrusted-event --Yes--> declare-allow_events{Declare allow_events?}
    declare-allow_events --Yes--> image-task{Image task?}
    declare-allow_events --No--> Not-pass
    image-task --No--> Pass
    image-task --Yes--> declare-allow_images{Declare allow_images?}
    declare-allow_images --No--> Not-pass
    declare-allow_images --Yes--> Pass
```

Explanation of Allow Requirement Checks:

1. In [untrusted events](./trigger-rule.md#untrusted-events),
   the pipeline configuration or trigger is uncontrollable.
   The configuration file must include `allow_events` to be referenced by untrusted event pipelines.

2. Pipelines may use third-party plugins.
   For security, the configuration file must declare `allow_images` to be referenced by plugin tasks.

```mermaid
flowchart LR
  strat([Slug check]) --> declare-allow_slugs{Declare allow_slugs?}
  declare-allow_slugs --Yes--> slug-matches-allow_slugs{Slug matches allow_slugs?}
  declare-allow_slugs --No--> Pass
  slug-matches-allow_slugs --Yes--> Pass
  slug-matches-allow_slugs --No--> Not-pass
```

```mermaid
flowchart LR
  strat([Branch check]) --> declare-allow_branches{Declare allow_branches?}
  declare-allow_branches --Yes--> branch-matches-allow_branches{Branch matches allow_branches?}
  declare-allow_branches --No--> Pass
  branch-matches-allow_branches --Yes--> Pass
  branch-matches-allow_branches --No--> Not-pass
```

Branch checked in `allow_branches` is same as [CNB\_BRANCH](./build-in-env.md#CNB_BRANCH).

```mermaid
flowchart LR
  strat([Event check]) --> declare-allow_events{Declare allow_events?}
  declare-allow_events --Yes--> event-matches-allow_events{Event matches allow_events?}
  declare-allow_events --No--> Pass
  event-matches-allow_events --Yes--> Pass
  event-matches-allow_events --No--> Not-pass
```

```mermaid
flowchart LR
  strat([Image check]) --> declare-allow_images{Declare allow_images?}
  declare-allow_images --Yes--> image-matches-allow_images{Image matches allow_images?}
  declare-allow_images --No--> Pass
  image-matches-allow_images --Yes--> Pass
  image-matches-allow_images --No--> Not-pass
```

Image check notes:

* Plugin task parameters can be set via `settingsFrom` or imported as env vars via `imports`.
  Both count as plugin task file references.
* When the image name has no tag or has the `:latest` tag,
  it matches `allow_images` using both `image-name` and `image-name:latest`. Either match is valid.
* Non-plugin task image is empty string and cannot match any glob pattern.
  Files with `allow_images` cannot be referenced by non-plugin tasks.
* **Note: Jobs with both image and script are script tasks using image as execution environment**
* Pipelines can declare image as build environment but not as plugin task.
  Files with `allow_images` cannot be referenced at pipeline level.

## Examples

### Pipeline Secret File Reference

```yaml
# Configuration file secret.yml in the keystore repository
allow_slugs: "p1/**"
allow_events: push
allow_branches: main
DOCKER_USER: docker-user
DOCKER_PWD: docker-pwd
```

```yaml title=".cnb.yml"
# Pipeline configuration file .cnb.yml
main:
  push:
    - services:
        - docker
      imports: https://cnbprod.alpha.qq.com/<your-repo-slug>/-/blob/main/xxx/secret.yml
      stages:
        - name: docker login
          script: |
            docker login -u ${DOCKER_USER} -p "${DOCKER_PWD}"
            # docker build xxx
            # docker push xxx
```

The pipeline references `secret.yml` from another repository,
but the trigger does not have read access to this file.

`secret.yml` declares `allow_slugs`, `allow_events`, and `allow_branches`:
if a repository under the `p1` organization triggers a `push` event on the `main` branch,
the pipeline can reference this secret file.

This ensures that only the owner or administrator of the secret repository can view or modify the sensitive content,
while still allowing it to be referenced by pipelines that meet the specified conditions.

### Plugin Task Parameter Reference

```yaml
# Configuration file image-settings.yml in the keystore repository
allow_images: "registry.com/image1/**"
allow_slugs: "p1/**"
arg1: arg1
arg2: arg2
```

```yaml title=".cnb.yml"
main:
  push:
    - stages:
        - name: image job
          image: registry.com/image1/print:latest
          settingsFrom:
            - https://cnbprod.alpha.qq.com/<your-repo-slug>/-/blob/main/xxx/image-settings.yml
```

If the image is created by a third party, there may be a risk of information leakage.
You can use `allow_images` to restrict the configuration file to plugin tasks with specific image names.

The image `registry.com/image1/print:latest` matches `registry.com/image1/**`, so the image check passes.
`allow_slugs` further restricts usage to pipelines under the `p1` organization.