Skip to content

Variables in scripts and profiles: Update language #39253

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
noahtalerman wants to merge 6 commits into
base: main
Choose a base branch
from
+11 −13
Open

Variables in scripts and profiles: Update language #39253

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d9b8f88
Variables in scripts and profiles: Update language
noahtalerman Feb 3, 2026
30fefcf
Update articles/secrets-in-scripts-and-configuration-profiles.md
noahtalerman Feb 3, 2026
200554b
Update secrets-in-scripts-and-configuration-profiles.md
noahtalerman Feb 5, 2026
6e1409f
Update articles/secrets-in-scripts-and-configuration-profiles.md
noahtalerman Feb 6, 2026
e8d12c3
Update articles/secrets-in-scripts-and-configuration-profiles.md
noahtalerman Feb 6, 2026
dab8a5a
Merge branch 'main' into noahtalerman-patch-73
noahtalerman Feb 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 11 additions & 14 deletions articles/secrets-in-scripts-and-configuration-profiles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,31 +24,29 @@ Variables are global, meaning they can be used in scripts and profiles across al

### GitOps

1. You must add the variable to your [GitHub](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository) or [GitLab](https://docs.gitlab.com/ci/variables/#define-a-cicd-variable-in-the-ui) repository's secrets to use them in GitOps.
1. First, add the variable to your [GitHub](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository) or [GitLab](https://docs.gitlab.com/ci/variables/#define-a-cicd-variable-in-the-ui) repository's secrets to use them in GitOps.

2. For the GitHub GitOps flow, they must also be added to the `env` section of your workflow file, as shown below:
2. Then, add to the `env` section of in your `workflows.yml` file, as shown below:

```yaml
env:
### Variables used by the gitops workflow ###
### Variables used by the GitOps workflow ###
FLEET_URL: ${{ secrets.FLEET_URL }}
FLEET_API_TOKEN: ${{ secrets.FLEET_API_TOKEN }}
FLEET_WORKSTATIONS_ENROLL_SECRET: ${{ secrets.FLEET_WORKSTATIONS_ENROLL_SECRET }}
FLEET_WORKSTATIONS_CANARY_ENROLL_SECRET: ${{ secrets.FLEET_WORKSTATIONS_CANARY_ENROLL_SECRET }}
### Secrets uploaded to Fleet for use in profiles and scripts ###
FLEET_SECRET_CERT_PASSWORD: ${{ secrets.FLEET_SECRET_CERT_PASSWORD }}
FLEET_SECRET_CERT_BASE64: ${{ secrets.FLEET_SECRET_CERT_BASE64 }}
WORKSTATIONS_ENROLL_SECRET: ${{ secrets.WORKSTATIONS_ENROLL_SECRET }}
```

When GitOps syncs the configuration, it looks for variables in scripts and profiles, extracts the variable's values from the environment, and uploads them to Fleet.
### Scripts and profiles

On subsequent GitOps syncs, if a variable is used by an updated configuration profile, the profile will be resent to the host device(s).
When GitOps runs, it looks for variables in scripts and profiles, extracts the variable's values from GitHub or GitLab, and uploads them to Fleet.

Variables aren't removed on GitOps runs. To remove a variable, delete it on the `Controls` > `Variables` page.
Profiles with variables are not validated during a GitOps dry run because the required variables may not exist or may be incorrect in the Fleet database. As a result, these profiles have a higher chance of failing during a non-dry run. The best practice is to test the script or profile by adding it to Fleet via the UI first.

If a variable's value changes, the profile will be resent to hosts.
Copy link
Member Author

@noahtalerman noahtalerman Feb 3, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If a variable's value changes, the profile will be resent to hosts.
If a variable's value changes, the profile will automatically be resent to hosts.

@getvictor can you please sanity check me here? Is this accurate?

Copy link
Member

@getvictor getvictor Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The language is a little confusing to me because we have FLEET_VAR_* which I think of as variables.

But yes, If a secret variable's ($FLEET_SECRET_*) value changes, the configuration profile will be resent to hosts.

Copy link
Member Author

@noahtalerman noahtalerman Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If a FLEET_VAR_* changes, profiles are automatically resent to hosts, right?

Reason we're going with "variables" here is because that's what we call both FLEET_VAR_* and FLEET_SECET_* when talking with users/customers. That's also what both are called in the UI. "You can use a Fleet variable for secrets."

Copy link
Member

@getvictor getvictor Feb 4, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, I don't think we can make a blanket statement for all FLEET_VAR_*
I think we need a matrix for supported profiles (macOS, DDM, Windows, Android profiles, Android certificates), which ones are supported for those profiles, and which ones get resent (per host, in some cases), when they change.

Copy link
Member Author

@noahtalerman noahtalerman Feb 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, that's right. We exactly already document which variables support retries: https://fleetdm.com/docs/configuration/yaml-files#variables:~:text=When%20this%20changes%2C-,Fleet%20will%20automatically%20resend%20the%20profile.,-%24FLEET_VAR_HOST_END_USER_IDP_FULL_NAME

Copy link
Member Author

@noahtalerman noahtalerman Feb 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated the PR.


> 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 team first.
If the variable is a secret (ex. API token), you can mask the variable by using the `FLEET_SECRET_` prefix. This way, when the profile is downloaded via the Fleet UI or API, the variable is masked as `FLEET_SECRET_`.

## Using the secret on a configuration profile
Variables aren't removed on GitOps runs. To remove a variable, delete it on the `Controls` > `Variables` page.

Here's an example profile with `$FLEET_SECRET_CERT_PASSWORD` and `$FLEET_SECRET_CERT_BASE64` variables:
```xml
Expand Down Expand Up @@ -92,7 +90,6 @@ Here's an example profile with `$FLEET_SECRET_CERT_PASSWORD` and `$FLEET_SECRET_

> In XML, certain characters (`&`, `<`, `>`, `"`, `'`) must be escaped because they have special meanings in the markup language. Fleet variables will be automatically escaped when used in a `.mobileconfig` configuration profile. For example, `&` will become `&amp;`.


## 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.
Expand Down
Loading