Variables in scripts and configuration profiles

In Fleet you can add variables, in scripts and configuration profiles. Variables are hidden when the script or configuration profile is viewed in the Fleet UI or API.

Configuration profiles can also use any of Fleet's built-in variables.

Add variables

A variable can be used in a script or configuration profile by specifying a variable in the format $FLEET_SECRET_MYNAME or ${FLEET_SECRET_MYNAME}. When the script or profile is sent to the host, Fleet will replace the variable with the variable's value. The prefix FLEET_SECRET_ is required to indicate that this is a variable, and Fleet reserves this prefix for variables.

For macOS and Linux scripts, if a variable doesn't have the $FLEET_SECRET_ prefix, it will be treated as a local environment variable.

UI

To add or delete a variable in the UI, go to Controls > Variables and click + Add custom variable:

Variables are global, meaning they can be used in scripts and profiles across all fleets.

GitOps

Add the variable to your GitHub or GitLab repository's secrets to use the variable in GitOps.
Define the variable in the env section of in your workflows.yml file, as shown below:

    env:
      ###  Variables used by the GitOps workflow ###
      FLEET_URL: ${{ secrets.FLEET_URL }}
      FLEET_API_TOKEN: ${{ secrets.FLEET_API_TOKEN }}
      WORKSTATIONS_ENROLL_SECRET: ${{ secrets.WORKSTATIONS_ENROLL_SECRET }}

Scripts and configuration profiles

During a GitOps run, Fleet scans scripts and profiles for variables, pulls their values from GitHub or GitLab, and uploads them to Fleet.

Profiles with variables aren’t validated during a GitOps dry run because the variables may be missing or incorrect in Fleet. This means they’re more likely to fail during a real run. Best practice: test the script or profile by adding it to Fleet via the UI first.

Some variables trigger a profile resend when their value changes. See which variables support this in the YAML reference docs.

If a variable is a secret (for example, an API token), prefix it with FLEET_SECRET_. This masks the value when viewed or downloaded from the Fleet UI or API. If a secret’s value changes, the profile is resent to hosts.

Variables aren't removed on GitOps runs. To remove a variable, delete it on the Controls > Variables page.

Profiles with variables are not entirely validated during a GitOps dry run because the required variables may not exist or may be incorrect in the database. As a result, these profiles have a higher chance of failing during a non-dry run. Test them by uploading to a small fleet first.

Using the secret on a configuration profile

Here's an example profile with $FLEET_SECRET_CERT_PASSWORD and $FLEET_SECRET_CERT_BASE64 variables:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadDisplayName</key>
    <!-- Note: Do not use $FLEET_SECRET_ variables in PayloadDisplayName -->
    <string>Certificate PKCS12</string>
    <key>PayloadIdentifier</key>
    <string>com.example.certificate</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>918ee83d-ebd5-4192-bcd4-8b4feb750e4b</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
    <key>PayloadContent</key>
    <array>
      <dict>
            <key>Password</key>
            <string>$FLEET_SECRET_CERT_PASSWORD</string>
            <key>PayloadContent</key>
            <data>${FLEET_SECRET_CERT_BASE64}</data>
            <key>PayloadDisplayName</key>
            <string>Certificate PKCS12</string>
            <key>PayloadIdentifier</key>
            <string>com.example.certificate</string>
            <key>PayloadType</key>
            <string>com.apple.security.pkcs12</string>
            <key>PayloadUUID</key>
            <string>25cdd076-f1e7-4932-aa30-1d4240534fb0</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
        </dict>
    </array>
</dict>
</plist>

Fleet variables are automatically escaped in Apple (.mobileconfig) and Windows (.xml) configuration profiles. For example, & will become &. Special characters outside of Fleet variables must be manually escaped because they have special meanings in XML.

Known limitations and issues

Apple MDM profiles: Fleet secret variables ($FLEET_SECRET_*) cannot be used in the PayloadDisplayName field of Apple configuration profiles. This field becomes the visible name of the profile and using secrets here could expose sensitive information. Place secrets in other fields like PayloadDescription, Password, or PayloadContent instead.
After changing a variable used by a Windows profile, that profile is currently not re-sent to the device when the GitHub action (or GitLab pipeline) runs: story #27351
Fleet does not hide the secret in script results. Don't print/echo your secrets to the console output.
There is no way to explicitly delete a secret variable. Instead, you can overwrite it with any value.
Do not use deprecated API endpoint(s) to upload profiles containing secret variables. Use endpoints documented in Fleet's REST API.

6.4 KiB Raw Blame History Unescape Escape