About recommended secrets
If a project needs user-specific secrets to be set up, you can prompt people to do this when they create a codespace. You do this by adding a setting to a dev container configuration file for the repository.
After you specify recommended secrets, if people have not already created those secrets in their personal settings for Codespaces, they will be prompted to do so when they use the advanced options method of creating a codespace. This is done on GitHub by clicking the Code button, then clicking the Codespaces tab, then selecting and clicking New with options.
Recommended secrets are listed at the bottom of the page.
Note: The names of the recommended secrets are only listed on this page when the container configuration on the selected branch specifies these secrets.
Each recommended secret is displayed in one of three ways:
- If the person has not set the recommended secret in their Codespaces settings, an input box is displayed, allowing them to create the secret now. A description and link to more information are displayed if you have configured them. Entering a value is optional.
- If the person has already created the recommended secret but has not associated it with this repository, they can select a checkbox to add this association. Doing so is optional.
- If the person has already created the recommended secret and associated it with this repository, a preselected checkbox is displayed.
When to specify recommended secrets for a project
You should use recommended secrets for development environment secrets that the user who creates the codespace, rather than the owner of the repository or organization, must provide. For example, if you have a public project, and users must provide a personal API key to run the application in your project, you can specify a recommended secret so that users will be prompted to provide the key as the value of the secret when they use the advanced options page to create a codespace.
Alternatively, for development environment secrets that the owner of the repository or organization can provide, such as API keys shared across a team, you can set secrets at the level of the repository or organization. For more information, see "Managing development environment secrets for your repository or organization."
Specifying recommended secrets in the dev container configuration
-
You can configure the codespaces that are created for your repository by adding settings to a
devcontainer.json
file. If your repository doesn't already contain adevcontainer.json
file, you can add one now. See "Adding a dev container configuration to your repository." -
Edit the
devcontainer.json
file, adding thesecrets
property at the top level of the file, within the enclosing JSON object. For example:JSON "secrets": { "NAME_OF_SECRET_1": { "description": "This is the description of the secret.", "documentationUrl": "https://example.com/link/to/info" }, "NAME_OF_SECRET_2": { } }
"secrets": { "NAME_OF_SECRET_1": { "description": "This is the description of the secret.", "documentationUrl": "https://example.com/link/to/info" }, "NAME_OF_SECRET_2": { } }
-
Add a property within
secrets
for each secret you want to recommend. For example, changeNAME_OF_SECRET_1
andNAME_OF_SECRET_2
, in the previous code example, to the names of the secrets that people should create in their personal settings for Codespaces. -
Optionally, supply a description for each secret and a URL for more information about this secret.
You can omit
description
anddocumentationUrl
, as shown byNAME_OF_SECRET_2
in the previous code example. -
Specify additional secrets, as required.
-
Save the file and commit your changes to the required branch of the repository.