Adding a Codespaces policy to constrain available machine types (#23814)

Co-authored-by: Mike McDonald <2575327+asciimike@users.noreply.github.com>
Co-authored-by: Steve Guntrip <12534592+stevecat@users.noreply.github.com>

content/billing/managing-billing-for-github-codespaces/about-billing-for-codespaces.md

@@ -48,6 +48,12 @@ For information on managing and changing your account's spending limit, see "[Ma
 
 {% data reusables.codespaces.exporting-changes %}
 
+## Limiting the choice of machine types
+
+The type of machine a user chooses when they create a codespace affects the per-minute charge for that codespace, as shown above. 
+
+Organization owners can create a policy to restrict the machine types that are available to users. For more information, see "[Restricting access to machine types](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types)."
+
 ## How billing is handled for forked repositories
 
 {% data variables.product.prodname_codespaces %} can only be used in organizations where a billable owner has been defined. To incur charges to the organization, the user must be a member or collaborator, otherwise they cannot create a codespace. 

content/billing/managing-billing-for-github-codespaces/managing-spending-limits-for-codespaces.md

@@ -57,3 +57,8 @@ Enterprise owners and billing managers can manage the spending limit for {% data
 Email notifications are sent to account owners and billing managers when spending reaches 50%, 75%, and 90% of your account's spending limit. 
 
 You can disable these notifications anytime by navigating to the bottom of the **Spending Limit** page.
+
+## Further reading
+
+- "[Restricting access to machine types](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types)"
+- "[Managing billing for Codespaces in your organization](/codespaces/managing-codespaces-for-your-organization/managing-billing-for-codespaces-in-your-organization)"

content/codespaces/codespaces-reference/understanding-billing-for-codespaces.md

@@ -54,3 +54,7 @@ Your codespace will be automatically deleted when you are removed from an organi
 ## Deleting your unused codespaces
 
 You can manually delete your codespaces in https://github.com/codespaces and from within {% data variables.product.prodname_vscode %}. To reduce the size of a codespace, you can manually delete files using the terminal or from within {% data variables.product.prodname_vscode %}.
+
+## Further reading
+
+- "[Managing billing for Codespaces in your organization](/codespaces/managing-codespaces-for-your-organization/managing-billing-for-codespaces-in-your-organization)"

content/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace.md

@@ -24,8 +24,7 @@ topics:
 
 You can choose a machine type either when you create a codespace or you can change the machine type at any time after you've created a codespace. 
 
-For information on choosing a machine type when you create a codespace, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)." 
-For information on changing the machine type within {% data variables.product.prodname_vscode %}, see "[Using {% data variables.product.prodname_codespaces %} in {% data variables.product.prodname_vscode %}](/codespaces/developing-in-codespaces/using-codespaces-in-visual-studio-code#changing-the-machine-type-in-visual-studio-code)."
+For information on choosing a machine type when you create a codespace, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)." For information on changing the machine type within {% data variables.product.prodname_vscode %}, see "[Using {% data variables.product.prodname_codespaces %} in {% data variables.product.prodname_vscode %}](/codespaces/developing-in-codespaces/using-codespaces-in-visual-studio-code#changing-the-machine-type-in-visual-studio-code)."
 
 ## Changing the machine type in {% data variables.product.prodname_dotcom %}
 
@@ -40,7 +39,11 @@ For information on changing the machine type within {% data variables.product.pr
 
    !['Change machine type' menu option](/assets/images/help/codespaces/change-machine-type-menu-option.png)
 
-1. Choose the required machine type.
+1. If multiple machine types are available for your codespace, choose the type of machine you want to use.
+
+   ![Dialog box showing available machine types to choose](/assets/images/help/codespaces/change-machine-type-choice.png)
+
+   {% data reusables.codespaces.codespaces-machine-type-availability %}
 
 2. Click **Update codespace**. 
 

content/codespaces/developing-in-codespaces/creating-a-codespace.md

@@ -80,9 +80,12 @@ If you would like to create a codespace for a repository owned by your personal
 
    ![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
 
-   If you are a member of an organization and are creating a codespace on a repository owned by that organization, you can select the option of a different machine type. From the dialog, choose a machine type and then click **Create codespace**.
+   If you are a member of an organization and are creating a codespace on a repository owned by that organization, you can select the option of a different machine type. From the dialog box, choose a machine type and then click **Create codespace**.
+
    ![Machine type choice](/assets/images/help/codespaces/choose-custom-machine-type.png)
 
+   {% data reusables.codespaces.codespaces-machine-type-availability %}
+
 {% endwebui %}
    
 {% vscode %}

content/codespaces/developing-in-codespaces/using-codespaces-in-visual-studio-code.md

@@ -36,28 +36,28 @@ Use the {% data variables.product.prodname_vs %} Marketplace to install the [{%
 {% mac %}
 
 {% data reusables.codespaces.click-remote-explorer-icon-vscode %}
-2. Click **Sign in to view {% data variables.product.prodname_dotcom %}...**.
+1. Click **Sign in to view {% data variables.product.prodname_dotcom %}...**.
 
    ![Signing in to view {% data variables.product.prodname_codespaces %}](/assets/images/help/codespaces/sign-in-to-view-codespaces-vscode-mac.png)
 
-3. To authorize {% data variables.product.prodname_vscode %} to access your account on {% data variables.product.product_name %}, click **Allow**.
-4. Sign in to {% data variables.product.product_name %} to approve the extension.
+1. To authorize {% data variables.product.prodname_vscode %} to access your account on {% data variables.product.product_name %}, click **Allow**.
+1. Sign in to {% data variables.product.product_name %} to approve the extension.
 
 {% endmac %}
 
 {% windows %}
 
 {% data reusables.codespaces.click-remote-explorer-icon-vscode %}
-2. Use the "REMOTE EXPLORER" drop-down, then click **{% data variables.product.prodname_github_codespaces %}**.
+1. Use the "REMOTE EXPLORER" drop-down, then click **{% data variables.product.prodname_github_codespaces %}**.
 
    ![The {% data variables.product.prodname_codespaces %} header](/assets/images/help/codespaces/codespaces-header-vscode.png)
 
-3. Click **Sign in to view {% data variables.product.prodname_codespaces %}...**.
+1. Click **Sign in to view {% data variables.product.prodname_codespaces %}...**.
 
    ![Signing in to view {% data variables.product.prodname_codespaces %}](/assets/images/help/codespaces/sign-in-to-view-codespaces-vscode.png)
 
-4. To authorize {% data variables.product.prodname_vscode %} to access your account on {% data variables.product.product_name %}, click **Allow**.
-5. Sign in to {% data variables.product.product_name %} to approve the extension.
+1. To authorize {% data variables.product.prodname_vscode %} to access your account on {% data variables.product.product_name %}, click **Allow**.
+1. Sign in to {% data variables.product.product_name %} to approve the extension.
 
 {% endwindows %}
 
@@ -68,8 +68,8 @@ Use the {% data variables.product.prodname_vs %} Marketplace to install the [{%
 ## Opening a codespace in {% data variables.product.prodname_vscode %}
 
 {% data reusables.codespaces.click-remote-explorer-icon-vscode %}
-2. Under "Codespaces", click the codespace you want to develop in.
-3. Click the Connect to Codespace icon.
+1. Under "Codespaces", click the codespace you want to develop in.
+1. Click the Connect to Codespace icon.
 
    ![The Connect to Codespace icon in {% data variables.product.prodname_vscode %}](/assets/images/help/codespaces/click-connect-to-codespace-icon-vscode.png)
 
@@ -80,17 +80,23 @@ Use the {% data variables.product.prodname_vs %} Marketplace to install the [{%
 You can change the machine type of your codespace at any time.
 
 1. In {% data variables.product.prodname_vscode %}, open the Command Palette (`shift command P` / `shift control P`).
-2. Search for and select "Codespaces: Change Machine Type."
+1. Search for and select "Codespaces: Change Machine Type."
 
    ![Searching for a branch to create a new {% data variables.product.prodname_codespaces %}](/assets/images/help/codespaces/vscode-change-machine-type-option.png)
 
-3. Click the codespace that you want to change.
+1. Click the codespace that you want to change.
 
    ![Searching for a branch to create a new {% data variables.product.prodname_codespaces %}](/assets/images/help/codespaces/vscode-change-machine-choose-repo.png)
 
-4. Choose the machine type you want to use. 
+1. Choose the machine type you want to use. 
 
-If the codespace is currently running, a message is displayed asking if you would like to restart and reconnect to your codespace now. Click **Yes** if you want to change the machine type used for this codespace immediately. If you click **No**, or if the codespace is not currently running, the change will take effect the next time the codespace restarts.
+   {% data reusables.codespaces.codespaces-machine-type-availability %}
+
+1. If the codespace is currently running, a message is displayed asking if you would like to restart and reconnect to your codespace now.
+
+   Click **Yes** if you want to change the machine type used for this codespace immediately.
+   
+   If you click **No**, or if the codespace is not currently running, the change will take effect the next time the codespace restarts.
 
 ## Deleting a codespace in {% data variables.product.prodname_vscode %}
 

content/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization.md

@@ -24,7 +24,7 @@ Organization owners can control which users in your organization can create and
 To use codespaces in your organization, you must do the following:
 
 - Ensure that users have [at least write access](/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization) to the repositories where they want to use a codespace. 
-- [Enable {% data variables.product.prodname_codespaces %} for users in your organization](#configuring-which-users-in-your-organization-can-use-codespaces). You can choose allow {% data variables.product.prodname_codespaces %} for selected users or only for specific users.
+- [Enable {% data variables.product.prodname_codespaces %} for users in your organization](#enable-codespaces-for-users-in-your-organization). You can choose allow {% data variables.product.prodname_codespaces %} for selected users or only for specific users.
 - [Set a spending limit](/billing/managing-billing-for-github-codespaces/managing-spending-limits-for-codespaces)
 - Ensure that your organization does not have an IP address allow list enabled. For more information, see "[Managing allowed IP addresses for your organization](/organizations/keeping-your-organization-secure/managing-allowed-ip-addresses-for-your-organization)."
 

content/codespaces/managing-codespaces-for-your-organization/index.md

@@ -13,6 +13,7 @@ children:
   - /managing-encrypted-secrets-for-your-repository-and-organization-for-codespaces
   - /managing-repository-access-for-your-organizations-codespaces
   - /reviewing-your-organizations-audit-logs-for-codespaces
+  - /restricting-access-to-machine-types
 shortTitle: Managing your organization
 ---
  

content/codespaces/managing-codespaces-for-your-organization/managing-billing-for-codespaces-in-your-organization.md

@@ -37,6 +37,8 @@ You can disable the use of {% data variables.product.prodname_codespaces %} in y
 
 You can also limit the individual users who can use {% data variables.product.prodname_codespaces %}. For more information, see "[Managing user permissions for your organization](/codespaces/managing-codespaces-for-your-organization/managing-user-permissions-for-your-organization)."
 
+You can limit the choice of machine types that are available for repositories owned by your organization. This allows you to prevent people using overly resourced machines for their codespaces. For more information, see "[Restricting access to machine types](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types)."
+
 ## Deleting unused codespaces
 
 Your users can delete their codespaces in https://github.com/codespaces and from within Visual Studio Code. To reduce the size of a codespace, users can manually delete files using the terminal or from within Visual Studio Code. 

content/codespaces/managing-codespaces-for-your-organization/managing-encrypted-secrets-for-your-repository-and-organization-for-codespaces.md

@@ -78,6 +78,6 @@ You can check which access policies are applied to a secret in your organization
 ![Secrets list](/assets/images/help/settings/actions-org-secrets-list.png)
 1. For more details on the configured permissions for each secret, click **Update**.
 
-## Further Reading
+## Further reading
 
 - "[Managing encrypted secrets for your codespaces](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)"

content/codespaces/managing-codespaces-for-your-organization/managing-repository-access-for-your-organizations-codespaces.md

@@ -30,6 +30,6 @@ To manage which users in your organization can use {% data variables.product.pro
 1. If you chose "Selected repositories", select the drop-down menu, then click a repository to allow the repository's codespaces to access other repositories owned by your organization. Repeat for all repositories whose codespaces you want to access other repositories.
     !["Selected repositories" drop-down menu](/assets/images/help/settings/codespaces-access-and-security-repository-drop-down.png)
 
-## Further Reading
+## Further reading
 
 - "[Managing repository access for your codespaces](/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces)"

content/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types.md

@@ -0,0 +1,94 @@
+---
+title: Restricting access to machine types
+shortTitle: Machine type access
+intro: 'You can set constraints on the types of machines users can choose when they create codespaces in your organization.'
+product: '{% data reusables.gated-features.codespaces %}'
+permissions: 'To manage access to machine types for the repositories in an organization, you must be an organization owner.'
+versions:
+  fpt: '*'
+  ghec: '*'
+type: how_to
+topics:
+  - Codespaces
+---
+
+## Overview
+
+Typically, when you create a codespace you are offered a choice of specifications for the machine that will run your codespace. You can choose the machine type that best suits your needs. For more information, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)." If you pay for using {% data variables.product.prodname_github_codespaces %} then your choice of machine type will affect how much your are billed. For more information about pricing, see "[About billing for Codespaces](/billing/managing-billing-for-github-codespaces/about-billing-for-codespaces)."
+
+As an organization owner, you may want to configure constraints on the types of machine that are available. For example, if the work in your organization doesn't require significant compute power or storage space, you can remove the highly resourced machines from the list of options that people can choose from. You do this by defining one or more policies in the {% data variables.product.prodname_codespaces %} settings for your organization.
+
+### Behavior when you set a machine type constraint
+
+If there are existing codespaces that no longer conform to a policy you have defined, these codespaces will continue to operate until they time out. When the user attempts to resume the codespace they are shown a message telling them that the currenly selected machine type is no longer allowed for this organization and prompting them to choose an alternative machine type.
+
+If you remove higher specification machine types that are required by the {% data variables.product.prodname_codespaces %} configuration for an individual repository in your organization, then it won't be possible to create a codespace for that repository. When someone attempts to create a codespace they will see a message telling them that there are no valid machine types available that meet the requirements of the repository's {% data variables.product.prodname_codespaces %} configuration.
+
+{% note %}
+
+**Note**: Anyone who can edit the `devcontainer.json` configuration file in a repository can set a minimum specification for machines that can be used for codespaces for that repository. For more information, see "[Setting a minimum specification for codespace machines](/codespaces/setting-up-your-project-for-codespaces/setting-a-minimum-specification-for-codespace-machines)."
+
+{% endnote %}
+
+If setting a policy for machine types prevents people from using {% data variables.product.prodname_codespaces %} for a particular repository there are two options:
+
+* You can adjust your policies to specifically remove the restrictions from the affected repository.
+* Anyone who has a codespace that they can no longer access, because of the new policy, can export their codespace to a branch. This branch will contain all of their changes from the codespace. They can then open a new codespace on this branch with a compliant machine type or work on this branch locally. For more information, see "[Exporting changes to a branch](/codespaces/troubleshooting/exporting-changes-to-a-branch)."
+
+### Setting organization-wide and repository-specific policies
+
+When you create a policy you choose whether it applies to all repositories in your organization, or only to specified repositories. If you set an organization-wide policy then any policies you set for individual repositories must fall within the restriction set at the organization level. Adding policies makes the choice of machine more, not less, restrictive.
+
+For example, you could create an organization-wide policy that restricts the machine types to either 2 or 4 cores. You can then set a policy for Repository A that restricts it to just 2-core machines. Setting a policy for Repository A that restricted it to machines with 2, 4, or 8 cores would result in a choice of 2-core and 4-core machines only, because the organization-wide policy prevents access to 8-core machines.
+
+If you add an organization-wide policy, you should set it to the largest choice of machine types that will be available for any repository in your organization. You can then add repository-specific policies to further restrict the choice.
+
+## Adding a policy to limit the available machine types
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+{% data reusables.organizations.click-codespaces %}
+1. Under "Codespaces", click **Policy**.
+
+   !["Policy" tab in left sidebar](/assets/images/help/organizations/codespaces-policy-sidebar.png)
+
+1. On the "Codespace policies" page, click **Create Policy**.
+1. Enter a name for your new policy.
+1. Click **Add constraint** and choose **Machine types**.
+
+   ![Add a constraint for machine types](/assets/images/help/codespaces/add-constraint-dropdown.png)
+
+1. Click {% octicon "pencil" aria-label="The edit icon" %} to edit the constraint, then clear the selection of any machine types that you don't want to be available.
+
+   ![Edit the machine type constraint](/assets/images/help/codespaces/edit-machine-constraint.png)
+
+1. In the "Change policy target" area, click the dropdown button.
+1. Choose either **All repositories** or **Selected repositories** to determine which repositories this policy will apply to.
+1. If you chose **Selected repositories**:
+   1. Click {% octicon "gear" aria-label="The settings icon" %}.
+
+      ![Edit the settings for the policy](/assets/images/help/codespaces/policy-edit.png)
+
+   1. Select the repositories you want this policy to apply to.
+   1. At the bottom of the repository list, click **Select repositories**.
+
+      ![Select repositories for this policy](/assets/images/help/codespaces/policy-select-repos.png)
+
+1. Click **Save**.
+
+## Editing a policy
+
+1. Display the "Codespace policies" page. For more information, see "[Adding a policy to limit the available machine types](#adding-a-policy-to-limit-the-available-machine-types)."
+1. Click the name of the policy you want to edit.
+1. Make the required changes then click **Save**.
+
+## Deleting a policy 
+
+1. Display the "Codespace policies" page. For more information, see "[Adding a policy to limit the available machine types](#adding-a-policy-to-limit-the-available-machine-types)."
+1. Click the delete button to the right of the policy you want to delete.
+
+   ![The delete button for a policy](/assets/images/help/codespaces/policy-delete.png)
+
+## Further reading
+
+- "[Managing spending limits for Codespaces](/billing/managing-billing-for-github-codespaces/managing-spending-limits-for-codespaces)"

content/codespaces/managing-codespaces-for-your-organization/reviewing-your-organizations-audit-logs-for-codespaces.md

@@ -21,6 +21,6 @@ When any member of your organization performs an action related to {% data varia
 
 The audit log includes details such as who performed the action, what the action was, and when the action was performed. For information on {% data variables.product.prodname_codespaces %} actions, see "[{% data variables.product.prodname_codespaces %} category actions](/organizations/keeping-your-organization-secure/reviewing-the-audit-log-for-your-organization#codespaces-category-actions)."
 
-## Further Reading
+## Further reading
 
 - "[Reviewing your security logs for {% data variables.product.prodname_codespaces %}](/codespaces/managing-your-codespaces/reviewing-your-security-logs-for-codespaces)"

content/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces.md

@@ -82,6 +82,6 @@ You can update the value of an existing secret, and you can change which reposit
 1. Read the warning, then click **OK**.
   ![Confirmation to delete secret](/assets/images/help/settings/codespaces-secret-delete-warning.png)
 
-## Further Reading
+## Further reading
 
 - "[Managing encrypted secrets for your repository and organization for {% data variables.product.prodname_codespaces %}](/codespaces/managing-codespaces-for-your-organization/managing-encrypted-secrets-for-your-repository-and-organization-for-codespaces)"

content/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces.md

@@ -24,6 +24,6 @@ When you enable access and security for a repository owned by your user account,
 1. If you chose "Selected repositories", select the drop-down menu, then click a repository to allow the repository's codespaces to access other repositories you own. Repeat for all repositories whose codespaces you want to access other repositories you own.
   !["Selected repositories" drop-down menu](/assets/images/help/settings/codespaces-access-and-security-repository-drop-down.png)
 
-## Further Reading
+## Further reading
 
 - "[Managing repository access for your organization's codespaces](/codespaces/managing-codespaces-for-your-organization/managing-repository-access-for-your-organizations-codespaces)"

content/codespaces/managing-your-codespaces/reviewing-your-security-logs-for-codespaces.md

@@ -22,6 +22,6 @@ When you perform an action related to {% data variables.product.prodname_codespa
 
 The security log includes details on what action occurred and when you performed it. For information about {% data variables.product.prodname_codespaces %} actions, see "[{% data variables.product.prodname_codespaces %} category actions](/github/authenticating-to-github/reviewing-your-security-log#codespaces-category-actions)".
 
-## Further Reading
+## Further reading
 
 - "[Reviewing your organization's audit logs for {% data variables.product.prodname_codespaces %}](/codespaces/managing-codespaces-for-your-organization/reviewing-your-organizations-audit-logs-for-codespaces)"

content/codespaces/setting-up-your-project-for-codespaces/index.md

@@ -15,5 +15,6 @@ children:
   - /setting-up-your-dotnet-project-for-codespaces
   - /setting-up-your-java-project-for-codespaces
   - /setting-up-your-python-project-for-codespaces
+  - /setting-a-minimum-specification-for-codespace-machines
 ---
 

content/codespaces/setting-up-your-project-for-codespaces/setting-a-minimum-specification-for-codespace-machines.md

@@ -0,0 +1,53 @@
+---
+title: Setting a minimum specification for codespace machines
+shortTitle: Setting a minimum machine spec
+intro: 'You can avoid under-resourced machine types being used for {% data variables.product.prodname_codespaces %} for your repository.'
+permissions: People with write permissions to a repository can create or edit the codespace configuration.
+versions:
+  fpt: '*'
+  ghec: '*'
+type: how_to
+topics:
+  - Codespaces
+  - Set up
+product: '{% data reusables.gated-features.codespaces %}'
+---
+
+## Overview
+
+When you create a codespace for a repository you are typically offered a choice of available machine types. Each machine type has a different level of resources. For more information, see "[Changing the machine type for your codespace](/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace#about-machine-types)."
+
+If your project needs a certain level of compute power, you can configure {% data variables.product.prodname_github_codespaces %} so that only machine types that meet these requirements are available for people to select. You configure this in the `devcontainer.json` file.
+
+{% note %}
+
+**Important:** Access to some machine types may be restricted at the organization level. Typically this is done to prevent people choosing higher resourced machines that are billed at a higher rate. If your repository is affected by an organization-level policy for machine types you should make sure you don't set a minimum specification that would leave no available machine types for people to choose. For more information, see "[Restricting access to machine types](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types)."
+
+{% endnote %}
+
+## Setting a minimum machine specification
+
+1. {% data variables.product.prodname_codespaces %} for your repository are configured in the `devcontainer.json` file. If your repository does not already contain a `devcontainer.json` file, add one now. See "[Add a dev container to your project](/free-pro-team@latest/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces)."
+1. Edit the `devcontainer.json` file, adding a `hostRequirements` property such as this:
+
+   ```json{:copy}
+   "hostRequirements": {
+      "cpus": 8,
+      "memory": "8gb",
+      "storage": "32gb" 
+   }
+   ```
+
+   You can specify any or all of the options: `cpus`, `memory`, and `storage`.
+   
+   To check the specifications of the {% data variables.product.prodname_codespaces %} machine types that are currently available for your repository, step through the process of creating a codespace until you see the choice of machine types. For more information, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)."
+   
+1. Save the file and commit your changes to the required branch of the repository.
+
+   Now when you create a codespace for that branch of the repository you will only be able to select machine types that match or exceed the resources you've specified.
+
+   ![Dialog box showing a limited choice of machine types](/assets/images/help/codespaces/machine-types-limited-choice.png)
+
+## Further reading
+
+- "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project)"

data/reusables/codespaces/codespaces-machine-type-availability.md

@@ -0,0 +1,5 @@
+   {% note %}
+
+   **Note**: Your choice of available machine types may be limited by a policy configured for your organization, or by a minimum machine type specification for your repository. For more information, see "[Restricting access to machine types](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types)" and "[Setting a minimum specification for codespace machines](/codespaces/setting-up-your-project-for-codespaces/setting-a-minimum-specification-for-codespace-machines)."
+
+   {% endnote %}

data/reusables/codespaces/creating-a-codespace-in-vscode.md

@@ -16,3 +16,5 @@ After you connect your account on {% data variables.product.product_location %}
 5. Click the machine type you want to develop in.
 
    ![Instance types for a new {% data variables.product.prodname_codespaces %}](/assets/images/help/codespaces/choose-sku-vscode.png)
+
+   {% data reusables.codespaces.codespaces-machine-type-availability %}