cnb:read-file

Reads the content of a local file, parses it into an object, and exports it as environment variables for use in subsequent tasks.

When to use it: sensitive information generated during the build process (such as dynamically obtained tokens, certificates, or passwords) cannot be written to the secret repository in advance. Write it to a file with a script, then use this built-in task to read and export it as environment variables — the value never passes through the logs, so nothing is leaked.

Differences from other ways of passing variables:

• ##[set-output key=value] is more convenient but prints the content to the logs, so it is not suitable for sensitive information.
• ##[set-secret key=*****] masks the value in the logs and is suitable for sensitive information, but it requires build machine support.
• imports can only import files that already exist in a remote repository, while this task only reads local files generated during the build process.

Not supported: this task only reads and exports the content. It does not encrypt the content, nor does it verify that sensitive values are masked in the logs.

• Applicable Events
• Parameters
• Output Results
• JSON Configuration Example
• Configuration Examples

Applicable Events

All Events

Parameters

filePath

• type: String
• required: true

Local file path.

Output Results

The task parses the file content according to the file suffix, writes the result object to result, and the object can be exported as environment variables through exports.

How each suffix is parsed:

Suffix	Parsing
.json	Parsed as a JSON object
.yml, .yaml	Parsed as a YAML object
.crt, .cer, .key, .pem, .pub, etc.	The file name plus suffix is the key, and the full file content is the value
Others	Parsed line by line as key=value, that is, a plain text file

For certificate-like suffixes, the key is the file name plus the suffix, with the . in the suffix replaced by _. For example, the key of server.key is server_key.

For how to use the from-key of exports, see Environment Variables.

JSON Configuration Example

The most typical usage: read a JSON configuration file and export its variables as environment variables.

db-config.json

{
  "host": "db.example.com",
  "port": 3306,
  "auth": {
    "username": "admin",
    "token": "readonly"
  },
  "pool": {
    "min": 1,
    "max": 10
  }
}

.cnb.yml

main:
  push:
    - stages:
        - name: read and export JSON config
          type: cnb:read-file
          options:
            filePath: db-config.json
          exports:
            host: DB_HOST # Top-level key
            port: DB_PORT # Top-level key, non-string values are converted to strings
            auth.username: DB_USER # Multi-level key, joining property names level by level with .
            auth.token: DB_TOKEN # Multi-level key, can go deeper
            pool.max: DB_POOL_MAX # Multi-level key, can go deeper
        - name: use exported variables
          script:
            - echo "DB_HOST: $DB_HOST"
            - echo "DB_USER: $DB_USER"
            - echo "DB_POOL_MAX: $DB_POOL_MAX"

Note

• Only leaf values are suitable for exporting as environment variables.
• When the value is an object (such as auth), it is exported as a JSON string (the JSON.stringify result).
• When the value is an array (such as pool), it is exported as a comma-joined string and cannot be expanded into multiple environment variables.
• Array elements are accessed by index, for example list.0.name.
• When the path does not exist, no error is raised and the environment variable is kept. If a variable with the same name was defined before, its original value is preserved and is not cleared or set to an empty string.

Export example: read a JSON file and export the variables in it as environment variables.

.cnb.yml

main:
  push:
    - env:
        myKey: deepWithEnvKey
      stages:
        - name: write env file
          script: echo "write env to myJson.json"
        - name: export env
          type: cnb:read-file
          options:
            filePath: myJson.json
          exports:
            myVar: ENV_MY_VAR
            deep.myVar: ENV_DEEP_MY_VAR # Specify a multi-level key
            $myKey.myVar: ENV_ENV_KEY_MY_VAR # Get the key specified through an environment variable
        - name: echo env
          script:
            - echo $ENV_MY_VAR
            - echo $ENV_DEEP_MY_VAR
            - echo $ENV_ENV_KEY_MY_VAR

The myJson.json read in the example above looks like this:

myJson.json

{
  "myVar": "myVar",
  "deep": {
    "myVar": "myVar in deep"
  },
  "deepWithEnvKey": {
    "myVar": "myVar in deepWithEnvKey"
  }
}

Configuration Examples

Write some variables needed for subsequent tasks to a file, then use this built-in task to read and export them as environment variables.

.cnb.yml

main:
  push:
    - stages:
        - name: build secret file
          script: |
            echo "API_TOKEN=xxx" > .env.local
        - name: read and export
          type: cnb:read-file
          options:
            filePath: .env.local
          exports:
            API_TOKEN: API_TOKEN
        - name: use env variable
          script: echo "use $API_TOKEN"