Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.
TypeScript acmeagentsai-agentscertificate-managementdevsecopsenvironment-variableskubernetesopen-sourcepampkipostgresprivate-caprivileged-access-managementsecret-managementsecret-managersecretssecrets-managementsecuritysecurity-toolsvault
docs: add a way to migrate the .infisical.json to .infisical.yaml
adilsonb02434df29ef
diff --git a/docs/cli/project-config-migration.mdx b/docs/cli/project-config-migration.mdxnew file mode 100644index 0000000000..6310220162--- /dev/null+++ b/docs/cli/project-config-migration.mdx@@ -0,0 +1,151 @@+---+title: "Migrate to .infisical.yaml"+description: "The Infisical CLI now reads project settings from `.infisical.yaml` instead of `.infisical.json`. Learn how to convert your project's configuration file."+---++## What changed++The CLI is moving away from `.infisical.json`. It now reads [project settings](/cli/project-config) from `.infisical.yaml`. The CLI still reads `.infisical.json` for now, but a future release will stop reading it.++## Who is affected++You're affected if you use an `.infisical.json` file anywhere, including:++- Repositories with a committed `.infisical.json`+- Container images that copy `.infisical.json` into the image++## Prerequisites++{/* TODO: replace X.Y.Z with the CLI release that ships .infisical.yaml and migrate-config */}++- Infisical CLI X.Y.Z or later on every machine that reads the file, including developer machines, CI pipelines, and container images ([upgrade the CLI](/cli/upgrade))++Older versions of the CLI don't read `.infisical.yaml`, so after you delete `.infisical.json`, those versions can't find the project linked to the directory.++## Migration steps++Convert the file with the `infisical migrate-config` command, or edit it by hand.++<Tabs>+ <Tab title="Run migrate-config">+ <Steps>+ <Step>+ In the directory that holds `.infisical.json`, run:++ ```bash+ infisical migrate-config+ ```++ The command copies every setting from `.infisical.json` into a new `.infisical.yaml` in the same directory, deletes `.infisical.json`, and prints the paths of both files:++ ```+ Migrated /home/user/my-app/.infisical.json to /home/user/my-app/.infisical.yaml.+ If this project is under version control, commit the new .infisical.yaml and the removal of .infisical.json.+ ```+ </Step>+ <Step>+ Commit the new file and the deletion of the old one:++ ```bash+ git add .infisical.yaml .infisical.json+ git commit -m "Migrate Infisical CLI config to .infisical.yaml"+ ```+ </Step>+ </Steps>++ The command converts one file. If your repository has more than one `.infisical.json`, such as one per package in a monorepo, run the command in each directory that holds one.++ </Tab>+ <Tab title="Edit the file by hand">+ <Steps>+ <Step>+ In the directory that holds `.infisical.json`, create a file named `.infisical.yaml`. The CLI doesn't read a file named `.infisical.yml`.+ </Step>+ <Step>+ Copy each field from `.infisical.json` to its key in `.infisical.yaml`:++ | `.infisical.json` field | `.infisical.yaml` key |+ | --- | --- |+ | `workspaceId` | `secrets-management.project-id` |+ | `defaultEnvironment` | `secrets-management.default-environment` |+ | `gitBranchToEnvironmentMapping` | `secrets-management.mappings.git-branch-to-environment` |+ | `defaultSecretPath` | `secrets-management.default-secret-path` |+ | `domain` | `general.domain` |++ <Note>+ `workspaceId` is the old name for the project ID, so copy its value into `project-id` as is.+ </Note>+++ For example, this `.infisical.json`:++ ```json .infisical.json+ {+ "workspaceId": "<project-id>",+ "defaultEnvironment": "dev",+ "gitBranchToEnvironmentMapping": {+ "main": "prod",+ "staging": "staging"+ },+ "defaultSecretPath": "/backend",+ "domain": "https://eu.infisical.com"+ }+ ```++ becomes this `.infisical.yaml`:++ ```yaml .infisical.yaml+ general:+ domain: https://eu.infisical.com+ secrets-management:+ project-id: <project-id>+ default-environment: dev+ default-secret-path: /backend+ mappings:+ git-branch-to-environment:+ main: prod+ staging: staging+ ```++ The CLI ignores keys it doesn't recognize, so if you misspell a key, the CLI drops that setting without reporting an error.+ </Step>+ <Step>+ Delete `.infisical.json`, then commit both changes.+ </Step>+ </Steps>++ </Tab>+</Tabs>++If a Dockerfile or CI script refers to `.infisical.json` by name, such as in a `COPY` instruction, change it to `.infisical.yaml`.++## Verify the migration++In the directory that holds `.infisical.yaml`, run a command that reads the file, such as:++```bash+infisical secrets+```++Check that the command lists the secrets from the project and environment you expect. If it reports that the project ID is missing, compare the keys in `.infisical.yaml` with the [field mapping](#migration-steps).++## FAQ++<AccordionGroup>+ <Accordion title="What if .infisical.json and .infisical.yaml are in the same directory?">+ The CLI can read both `.infisical.yaml` and `.infisical.json`. But+ `.infisical.yaml` takes precedence+ </Accordion>+ <Accordion title="Can I run infisical init instead of migrate-config?">+ `infisical init` writes a new `.infisical.yaml` that holds only the project+ ID, so you lose the environment, branch mapping, folder, and instance+ settings from `.infisical.json`. To keep those settings, run `infisical+ migrate-config`.+ </Accordion>+ <Accordion title="How do I hide the deprecation notice?">+ Set the `INFISICAL_DISABLE_WORKSPACE_CONFIG_MIGRATION_NOTICE` environment+ variable to any value, such as `true`. The CLI prints the notice at most+ once a day and writes it to standard error, so the notice doesn't change the+ output of commands like `infisical export`.+ </Accordion>+</AccordionGroup>diff --git a/docs/cli/project-config.mdx b/docs/cli/project-config.mdxindex 081aa7d6f5..42b0cab860 100644--- a/docs/cli/project-config.mdx+++ b/docs/cli/project-config.mdx@@ -3,12 +3,16 @@ title: "Project configuration"description: "Configure how the Infisical CLI interacts with your directory."----`.infisical.json` links a directory to an [Infisical project](/documentation/platform/project). When you run a command such as [`infisical run`](/cli/reference#run) or [`infisical secrets`](/cli/reference#secrets) in that directory, the CLI reads the project from the file, so you don't have to pass [`--projectId`](/cli/reference#run--flag-projectid).+<Warning>+ `.infisical.yaml` replaces `.infisical.json`, which is deprecated. The CLI still reads `.infisical.json`, so directories that have one keep working without any changes. To move to the new format, [convert it to `.infisical.yaml`](/cli/project-config-migration).+</Warning>++`.infisical.yaml` links a directory to an [Infisical project](/documentation/platform/project). When you run a command such as [`infisical run`](/cli/reference#run) or [`infisical secrets`](/cli/reference#secrets) in that directory, the CLI reads the project from the file, so you don't have to pass [`--projectId`](/cli/reference#run--flag-projectid).The file can also [choose an environment for you](#set-the-environment) and [pin the Infisical instance](#set-the-infisical-instance) the project lives on.<Info>-The `.infisical.json` file doesn't include any sensitive values and is safe to commit to version control.+The `.infisical.yaml` file doesn't include any sensitive values and is safe to commit to version control.</Info>## Create the file@@ -19,64 +23,63 @@ In the root of your codebase, run:infisical init```-Select the project when prompted. The CLI writes `.infisical.json` to the current directory:+Select the project when prompted. The CLI writes `.infisical.yaml` to the current directory:-```json .infisical.json-{- "workspaceId": "<project-id>",- "defaultEnvironment": "",- "gitBranchToEnvironmentMapping": null-}+```yaml .infisical.yaml+general: {}+secrets-management:+ project-id: <project-id>+ default-environment: ""+ mappings:+ git-branch-to-environment: {}```-`workspaceId` is the project's ID. The other fields are empty until you set them, as described in the sections that follow. If you run [`infisical init`](/cli/reference#init) again, the CLI replaces the file with a new one that holds only the project ID, so you lose any settings you added.+`project-id` is the project's ID. The other settings are empty until you set them, as described in the sections that follow. If you run [`infisical init`](/cli/reference#init) again, the CLI replaces the file with a new one that holds only the project ID, so you lose any settings you added.<Note>- If you authenticate as a [machine identity](/documentation/platform/identities/machine-identities), `infisical run`, [`infisical export`](/cli/reference#export), and `infisical secrets` don't read `workspaceId`. Pass the project with `--projectId` or the `INFISICAL_PROJECT_ID` environment variable instead.+ If you authenticate as a [machine identity](/documentation/platform/identities/machine-identities), `infisical run`, [`infisical export`](/cli/reference#export), and `infisical secrets` don't read `project-id`. Pass the project with `--projectId` or the `INFISICAL_PROJECT_ID` environment variable instead.</Note>## Set the environment-Without an environment setting, commands read secrets from your project's [`dev` environment](/documentation/platform/secrets-mgmt/project#project-environments) unless you pass [`--env`](/cli/reference#run--flag-env). To use a different environment by default, set `defaultEnvironment` to the environment's slug:+Without an environment setting, commands read secrets from your project's [`dev` environment](/documentation/platform/secrets-mgmt/project#project-environments) unless you pass [`--env`](/cli/reference#run--flag-env). To use a different environment by default, set `default-environment` to the environment's slug:-```json .infisical.json-{- "workspaceId": "<project-id>",- "defaultEnvironment": "staging"-}+```yaml .infisical.yaml+secrets-management:+ project-id: <project-id>+ default-environment: staging```-To pick the environment from the Git branch you're on, map branch names to environment slugs in `gitBranchToEnvironmentMapping`:--```json .infisical.json-{- "workspaceId": "<project-id>",- "defaultEnvironment": "dev",- "gitBranchToEnvironmentMapping": {- "main": "prod",- "staging": "staging"- }-}+To pick the environment from the Git branch you're on, map branch names to environment slugs under `mappings.git-branch-to-environment`:++```yaml .infisical.yaml+secrets-management:+ project-id: <project-id>+ default-environment: dev+ mappings:+ git-branch-to-environment:+ main: prod+ staging: staging```-The CLI matches only the last part of a branch name, after the final `/`. For example, the branch `release/staging` matches the key `staging`. If your current branch has no mapping, or you aren't on a branch (such as when you check out a specific commit), the CLI falls back to `defaultEnvironment`.+The CLI matches only the last part of a branch name, after the final `/`. For example, the branch `release/staging` matches the key `staging`. If your current branch has no mapping, or you aren't on a branch (such as when you check out a specific commit), the CLI falls back to `default-environment`.The CLI picks the environment in this order:1. The `--env` flag2. The environment mapped to your current Git branch-3. `defaultEnvironment`+3. `default-environment`4. `dev`## Set the Infisical instance-If your project is on EU Cloud, a dedicated instance, or a self-hosted instance, set `domain` to the instance's address:+If your project is on EU Cloud, a dedicated instance, or a self-hosted instance, set `domain` under `general` to the instance's address:-```json .infisical.json-{- "workspaceId": "<project-id>",- "domain": "https://eu.infisical.com"-}+```yaml .infisical.yaml+general:+ domain: https://eu.infisical.com+secrets-management:+ project-id: <project-id>````domain` must be a URL that starts with `https://` or `http://`, or the CLI ignores it and prints a warning.@@ -89,7 +92,7 @@ The CLI picks the instance in this order:1. The [`--domain`](/cli/reference#global-flags--flag-domain) flag2. The `INFISICAL_DOMAIN` environment variable, or the older `INFISICAL_API_URL` if `INFISICAL_DOMAIN` isn't set-3. `domain` in `.infisical.json`+3. `domain` in `.infisical.yaml`4. US Cloud (`https://app.infisical.com`)If you log in with your own account, [`infisical login`](/cli/reference#login) uses `domain` to choose the instance to log in to. After that:@@ -98,12 +101,12 @@ If you log in with your own account, [`infisical login`](/cli/reference#login) u- If you pass `--domain` or set `INFISICAL_DOMAIN` to a different instance than the one you logged in to, the command fails<Warning>- The CLI sends every request and credential to the instance in `domain`. Because `.infisical.json` is usually committed, anyone who can change the file in your repository can change where the CLI sends them. Each time the CLI uses `domain` from the file, it prints a warning that names the host. Only set `domain` to an instance you trust, and check it when you clone a repository you don't control.+ The CLI sends every request and credential to the instance in `domain`. Because `.infisical.yaml` is usually committed, anyone who can change the file in your repository can change where the CLI sends them. Each time the CLI uses `domain` from the file, it prints a warning that names the host. Only set `domain` to an instance you trust, and check it when you clone a repository you don't control.</Warning>## Use the file from another directory-The CLI looks for `.infisical.json` in the current directory, then in each parent directory up to the root of the file system. This means that if you have an `.infisical.json` file in the root of your codebase, that configuration applies to every directory under it.+The CLI looks for `.infisical.yaml` in the current directory, then in each parent directory up to the root of the file system. This means that if you have an `.infisical.yaml` file in the root of your codebase, that configuration applies to every directory under it.To read the project from a file somewhere else, such as one package's directory in a monorepo, pass the directory to `infisical run` with [`--project-config-dir`](/cli/reference#run--flag-project-config-dir):@@ -112,27 +115,27 @@ infisical run --project-config-dir ./services/api -- npm run dev```<Note>-`--project-config-dir` only sets the project. The environment and instance settings still come from the `.infisical.json` the CLI finds from your current directory.+`--project-config-dir` only sets the project. The environment and instance settings still come from the `.infisical.yaml` the CLI finds from your current directory.</Note>## Field reference-<ResponseField name="workspaceId" type="string">+<ResponseField name="secrets-management.project-id" type="string">The ID of the project to read secrets from. Not used when you authenticate as a machine identity.</ResponseField>-<ResponseField name="defaultEnvironment" type="string">+<ResponseField name="secrets-management.default-environment" type="string">The environment slug to use when `--env` isn't passed and no branch mapping matches.</ResponseField>-<ResponseField name="gitBranchToEnvironmentMapping" type="object">-Maps branch names to environment slugs, such as `{ "main": "prod" }`. Keys match only the last part of a branch name, after the final `/`.+<ResponseField name="secrets-management.mappings.git-branch-to-environment" type="object">+Maps branch names to environment slugs, such as `main: prod`. Keys match only the last part of a branch name, after the final `/`.</ResponseField>-<ResponseField name="defaultSecretPath" type="string">+<ResponseField name="secrets-management.default-secret-path" type="string">The folder to read secrets from when [`--path`](/cli/reference#secrets-agent-proxy-run--flag-path) and `INFISICAL_SECRET_PATH` aren't set. Only the [`infisical secrets agent-proxy`](/cli/reference#secrets-agent-proxy) commands read it.</ResponseField>-<ResponseField name="domain" type="string">+<ResponseField name="general.domain" type="string">The Infisical instance to connect to, such as `https://eu.infisical.com`. Must start with `https://` or `http://`.</ResponseField>diff --git a/docs/docs.json b/docs/docs.jsonindex 2d0977f3b4..14947ab1d3 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -1333,6 +1333,7 @@"pages": ["cli/overview","cli/cloudsmith-migration",+ "cli/project-config-migration",{"group": "Get started","pages": [