Skip to content

#BE8488 - Env. Group Updates #1185

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
SarpBakis23 wants to merge 2 commits into
base: develop
Choose a base branch
from
+222 −94
Open

#BE8488 - Env. Group Updates #1185

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f68d7c8
Env. Group Updates
SarpBakis23 Mar 23, 2026
c43c9e0
fix
SarpBakis23 Mar 23, 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
163 changes: 115 additions & 48 deletions docs/build/build-environment-variables/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,15 @@ import ContentRef from '@site/src/components/ContentRef';

### Creating environment variable groups

To create an environment variable group, select Environment Variables from the build module. Click on the orange + icon and enter the name of the group into the input box, press enter to save the group name and create the group.
To create an environment variable group, select Environment Variables from the build module. Click on the orange **...** icon and select '**Add Variable Group**'. Then, enter the name of the group into the input box, and press Enter to create the group.

<Screenshot url='https://cdn.appcircle.io/docs/assets/be-3108-var2.png' />
<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-6.png' />

### Adding key and text-based value pairs

To add an environment variable to the group, select the "Text" tab from the top and use the inputs below. Enter a key name, then enter the value for the key and press enter.

<Screenshot url='https://cdn.appcircle.io/docs/assets/be-3108-var3.png' />
<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-5.png' />

You can add as many environment variables as you need.

Expand All @@ -32,7 +32,7 @@ Variables that need to be secret can be hidden using the lock icon. Such variabl

Please note that some environment variables may need to be duplicated to be used in different groups for different purposes.

<Screenshot url='https://cdn.appcircle.io/docs/assets/be-3108-var1.png' />
<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-3.png' />

### Adding files as environment variables

Expand All @@ -42,82 +42,149 @@ To add a file, select the "File" tab from the top and enter a key name from the

Then press add to upload the file.

<Screenshot url='https://cdn.appcircle.io/docs/assets/be-3108-var4.png' />
<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-2.png' />

<Screenshot url='https://cdn.appcircle.io/docs/assets/be-3108-var5.png' />
<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-1.png' />

:::info

When you upload a file as an environment variable, file name is not preserved. The reason of this to prevent file name conflicts. You can upload different files with same name and can use their keys to refer them. You need to use your key to find the location of this file and then you can read the contents of this file.

:::

### Downloading environment variables
:::tip Editing Encrypted Variables
You can edit encrypted variables by clicking the Edit option, just like text variables. The original value will not be displayed for security reasons; however, the updated value will be saved.
:::

### Exporting environment variable groups

You can export environment variable groups in bulk as a `.zip` file.

To export variable groups, click on the three dots icon next to **Variable Groups** and select **Export Variable Group**.

<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-8.png' />

You can download and view environment variables in **JSON** format. For this, you can use the "Download" button by clicking on the three dots next to one of the variable groups under "Build > Environment Variables > Variable Groups".
<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-10.png' />

In the downloaded file content, you will see a structure with **key-value** pairs.
In the export modal:

In addition, if the value part of the environment variable is set to hidden during the text-based environment variable addition process, the "isSecret" value will be `true` and the key, along with the value **will not** be listed in the downloaded file. The same rule is valid for file type variables. If it is not hidden, this value will be `false`, and the value will be visible.
- You can select one or more environment variable groups (e.g., Prod, Dev, Staging).
- All selected groups will be included in the exported file.
- The export will be downloaded as a `.zip` file.

<Screenshot url='https://cdn.appcircle.io/docs/assets/BE6155-variable1.png' />
<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-11.png' />

:::info
An example of environment variable downloaded as a JSON file:
- Secret variables and file contents are not exposed directly for security reasons.
- Exporting multiple groups at once helps you back up or migrate configurations easily.
:::

An example of environment variable group downloaded as a JSON file:

```json
[
{
"key": "API_URL",
"value": "https://api.example.com",
"isSecret": false,
"isFile": false,
"id": "API_URL"
}
]
{"Id":"8260f439-d074-4f10-9361-66fe96480904",
"Name":"Prod",
"Variables":
[
{"Key":"API_URL",
"Value":"https://qa.example.com",
"IsSecret":false,"IsFile":false},
{"Key":"API_SECRET",
"Value":"",
"IsSecret":true,"IsFile":false},
{"Key":"API_KEY",
"Value":"",
"IsSecret":true,"IsFile":false},
{"Key":"TestFile",
"Value":"ac_post_process_output-2.json",
"IsSecret":false,"IsFile":true}]},
{"Id":"03bc80ee-972d-4214-9963-a4bfa8fd2d1c",
"Name":"Dev",
"Variables":
[{"Key":"test",
"Value":"",
"IsSecret":true,"IsFile":false}]},
{"Id":"f71c685c-5844-4099-9561-a12e76f667bd",
"Name":"Staging",
"Variables":
[{"Key":"test2",
"Value":"",
"IsSecret":true,"IsFile":false}]
}]
```

As seen in the example above;

- if the **isSecret** value is `false`, it has visible value
- if the **isSecret** value is `true` or **isFile** value is `true` , the key and the value will not be downloaded.
:::

### Uploading environment variables
### Importing environment variable groups

The Upload feature allows users to bulk-import environment variables into any existing Variable Group (e.g., Staging, Prod, or Dev) within the Build > Environment Variables section.
You can import environment variable groups in bulk using a `.zip` file.

This feature streamlines the process of configuring variables by enabling users to upload a predefined JSON file instead of manually entering each variable.
To import variable groups, click on the three dots icon next to **Variable Groups** and select **Import Variable Group**.

The uploadable file must be a `.json` file with an array of variable objects. Each variable object must include the following fields:
<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-7.png' />

<Screenshot url='https://cdn.appcircle.io/docs/assets/BE6155-variable2.png' />
<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-9.png' />

```json
[
{
"key": "API_URL",
"value": "https://api.example.com",
"isSecret": false,
"isFile": false,
"id": "API_URL"
},
{
"key": "API_KEY",
"value": "12345-abcde-67890-fghij",
"isSecret": true,
"isFile": false,
"id": "API_KEY"
}
]
```
In the import flow:

1. Upload a `.zip` file that contains environment variable groups.
2. On the next screen, select the groups you want to import.
3. Review the variables within each group before confirming.

<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-12.png' />


If a variable group or variable already exists, it will be marked with an `Exists` tag.

You can control how conflicts are handled using the following options:

- **Overwrite if there is existing group**: Replaces the entire group and all its variables.
- **Overwrite if there is existing variables**: Updates only the existing variables with new values.

<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-13.png' />

:::warning
- File type variables (isFile: `true`) cannot be uploaded using JSON. These must be added manually via the UI.
- The Download feature does not include secret values or file contents for security reasons.
- You can edit your own JSON files to update variables in a group. However, duplicated keys are not allowed.
:::info
- Existing variables or groups will not be overwritten unless the corresponding overwrite option is enabled.
- File-based variables are included in the import process via the `.zip` file.
:::

### Sharing environment variable groups

You can share environment variable groups from the root organization to sub-organizations.

To share a variable group, click on the three dots icon next to a group and select **Share**.

<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-30.png' />

In the share modal:

- You can select specific sub-organizations to share the variable group with.

<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-31.png' />

- Optionally, enable **Share with all sub-organizations** to automatically share the group with all existing and future sub-organizations.

<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-32.png' />

After sharing:

- Shared variable groups will be marked with a **Shared** tag in the root organization.

<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-33.png' />

- In sub-organizations, these groups will appear with an **Inherited** tag.

<Screenshot url='https://cdn.appcircle.io/docs/assets/BE8488-34.png' />

:::info
- Users in sub-organizations cannot edit, rename, or delete inherited variable groups.
- Any updates made in the root organization will be reflected in all shared sub-organizations.
:::

#### Using environment variable groups in builds

Environment variable groups can be used in builds to extend the workflow and add additional actions to workflow steps.
Expand Down
Loading