Google Cloud projects

Every Apps Script project uses Google Cloud to manage authorization, advanced services, and other details. To configure and manage these settings, every Apps Script project has an associated Google Cloud project. Your script project can use a default project that Apps Script automatically creates, or a standard project that you create yourself. In general, default projects are good for everyday or simple scripts, but you should use a standard project for any application that is complex, commercial quality, or is intended for publication.

You can switch from a default project to a standard project at any time, but you can't switch back to use a default project. It's best to select the Google Cloud project your script uses early in development. Switching later can cause complications, like requiring your users to re-authorize.

Default Google Cloud projects

When you create an Apps Script project, Apps Script creates a default Google Cloud project that operates in the background.

  • For most scripts, you never need to see or adjust this default project. Apps Script handles the necessary interactions with Google Cloud. For example, if you activate an advanced service in the Apps Script editor, Apps Script activates the advanced service in the default Google Cloud project when you save the script project.
  • For some scripts, you need to interact with the Google Cloud console. In these cases, your script must instead use a standard Google Cloud project. For example, to view Google Cloud logs in the Google Cloud console, your script must use a standard project.

View or update default Google Cloud projects

Most users can’t directly locate, view, or edit default projects in the Google Cloud console. Admins and domain users that have the resourcemanager.projects.list permission on the parent Google Cloud folder can view and configure default projects.

  • For Google Workspace customers, default projects fall under the Organization root > system-gsuite > apps-script folder in the Cloud Resource Hierarchy. Don't delete these folders. If you do, scripts can't create default projects and won't execute properly.
  • For non-Google Workspace customers, default projects are unparented in the Resource Hierarchy.

Delete default Google Cloud projects

If you're an admin, you can delete default Google Cloud projects like you would standard Google Cloud projects. See Delete Apps Script Google Cloud projects.

If you’re not an admin, you can’t delete default projects. However, Apps Script deletes default projects in the following scenarios:

  • If you delete the script project or switch it to use a standard project, Apps Script deletes the default project attached to the script along with any settings or information it contains.
  • If a script doesn't run for 180 days or more, Apps Script deletes its associated default project. If the script runs after Apps Script deletes its default project, Apps Script creates one for the script.

Standard Google Cloud projects

Default Google Cloud projects are the best option for most script projects, unless you need to manually configure the project. In these situations, you must switch your script project to use a standard project.

The following sections describe when Apps Script requires a standard project, the properties of such projects, and common tasks done with them. You can only perform the below tasks with standard projects.

When Apps Script requires standard Google Cloud projects

You must use a standard project in the following situations:

Standard Google Cloud project properties

Standard projects have the following properties:

  • You can access all of the Google Cloud settings for the project directly from the Google Cloud console. This lets you activate APIs, adjust authorization credentials, and configure other details.
  • When you delete a script project or switch it to use another standard project, the original standard project remains and can be reused.
  • When you activate an advanced service in a script project, you must manually activate the corresponding API in the standard project.
  • Multiple script projects and other apps can share the same standard project. If you intend to publish a script project to the Google Workspace Marketplace as an add-on, it must have its own standard project. Published apps can't share Google Cloud projects with other apps.
  • If you want to execute functions in a script project from another app using the Apps Script API's scripts.run method, the script project and the calling application must share the same standard project.
  • When Apps Script asks a user to authorize a script that uses a standard project, the Google Cloud project name is used to identify the script (not the script project name). For this reason, be sure to set an appropriate Google Cloud project name.

Access a standard Google Cloud project

To access the standard project associated with your script project, do the following:

New editor

  1. Open the Apps Script project.
  2. At the left, click Project Settings .
  3. Under Google Cloud Platform (GCP) Project, click the project number.

Legacy editor

  1. Open the script in the Apps Script editor.
  2. Select Resources > Cloud Platform project.
  3. In the dialog that opens, click the top link that references the GCP project name.

You can also find a standard project directly on the Google Cloud console Manage Resources page.

Activate an API in a standard Google Cloud project

Often an Apps Script application needs access to another Google API. To do this, you must activate the API in the corresponding Google Cloud project. Activate an API by doing the following:

  1. Open the Google Cloud project.
  2. Click Menu > APIs & Services.
  3. Click Enable APIs and Services.
  4. In the search box, enter the API you want to activate and press Enter.
  5. Click the API from the search results and then click Enable to activate the API for this Google Cloud project.

You might be prompted to accept the Terms of Service for Google APIs or Google Cloud. Review the Terms of Service carefully before accepting them.

Depending on the application, you might also need to configure the API by selecting it in the APIs & Services dashboard.

Determine the ID & number of a standard Google Cloud project

All Google Cloud projects have a project name, project ID, and project number. Occasionally, you must have these identifiers to configure services or complete other tasks.

To determine your standard project's ID and number, do the following:

  1. Open the Google Cloud project.
  2. At the top-right, click More > Project settings.
  3. View the Project name, Project ID, and Project number in the resulting Settings panel. The Project number consists only of digits, while the Project ID is alphanumeric. You can edit the Project name, which displays to users during authorization prompts.

View Google Cloud logs & error reports in the Google Cloud console

If you're using Cloud logging or error reporting for your script project, you can view those logs and reports in the Google Cloud console by doing the following:

  1. Open the Google Cloud project.
  2. Click Menu .
  3. Scroll down to the Operations section and click Logging > Logs explorer.
  4. To view error reports, scroll down to the Operations section and click Error Reporting. If you're prompted to set up error reporting, this means that your script project hasn't logged any exceptions yet.

When using services that require OAuth, Google prompts users to authorize those services. The OAuth consent screen settings let you set some of the information that Google presents to users, such as the application name and Terms of Service URL.

Default Google Cloud projects create a consent screen automatically from the Apps Script project details; you can't adjust those settings. Standard Google Cloud projects let you customize this information. You can configure your script's consent screen by doing the following:

  1. Open the Google Cloud project.
  2. Click Menu > APIs & Services > Credentials.
  3. Click Configure consent screen.
  4. Fill in each section of the consent screen workflow.
  5. To record your changes at each stage of the workflow, click Save and continue.

Create OAuth credentials

Apps Script usually sets up OAuth for the services your script uses. For some applications, you must create additional OAuth credentials (client IDs and client secrets). You can only do this with standard projects.

To create a client ID and client secret for your script project, do the following:

  1. Open the Google Cloud project.
  2. Click Menu > APIs & Services > Credentials.
  3. Click Create credentials > OAuth client ID.
  4. Under Application type, select your application type and fill in the resulting form if needed. When finished, click Create.
  5. In the dialog that appears, click Download JSON. You can use this file to configure OAuth.

Add additional owners to a standard Google Cloud project

You can add additional owners or other roles to a standard project. If you're collaborating on a project, this helps ensure that someone on your team always has access to the script project's Google Cloud settings.

You can add additional owners or other roles to a standard project by doing the following. You must have edit permissions for the project to make any of these changes:

  1. Determine who your collaborators should be. We recommended that you create or use an existing Google Group. You can also specify domains in the collaborator list to include all users in that domain.
  2. Open the script's Google Cloud project.
  3. Click Menu > IAM & admin > IAM.
  4. At the top, click Add.
  5. Follow the on-screen instructions to add one or more new members and their roles to the Google Cloud project. You can add individual emails, Google Groups, or domains as new members.
  6. Click Save.

Group multiple scripts with a single Google Cloud project

You can have multiple Apps Script projects share the same standard Google Cloud project. To do this, create a standard project and then switch each script project to use it. You can't do this with default projects.

Switch to a different standard Google Cloud project

You can switch a script project so that it uses a different standard Google Cloud project. You must switch to a standard project if your script requires manual configuration of the Google Cloud project. To learn more about when you need to use a standard project, see standard Google Cloud projects.

To switch a script's existing Google Cloud project over to another Google Cloud project, follow these steps:

New editor

  1. If you don't have a suitable Google Cloud project, create one by following the Create a project instructions. Set a memorable project name so that you can locate it on the Google Cloud console Manage Resources page. Apps Script uses this name when asking users to authorize the script.
  2. If you want to use an existing project, open the Google Cloud console Manage Resources page and locate an existing project to use. You must have resourcemanager.projects.update permissions for the project. You can't use a project that was automatically created by Apps Script.
  3. Determine the Project number of your Google Cloud project.
  4. Open the script whose Google Cloud project you want to replace.
  5. At the left, click Project Settings .
  6. Under Google Cloud Platform (GCP) Project, click Change project.
  7. Enter the new project number and click Set project.

Legacy editor

  1. If you don't have a suitable GCP project, create a new one by following the Create a project instructions. Otherwise, open the Google Cloud console Manage Resources page and locate an existing GCP project to use. You must have edit permissions for the GCP project and you must be able to view its settings in the Google Cloud console. The new project can't be one that was automatically created by Apps Script.
  2. Set a memorable GCP project name so that you can more easily locate it in the Google Cloud console Manage Resources page. This name is also used to identify the script when Apps Script asks users to authorize it.
  3. Determine the Project number of your GCP project.
  4. In the Apps Script editor, open the script whose GCP project you want to replace.
  5. Click Resources > Cloud Platform project.
  6. In the Change Project section, paste the project number you copied into the text field, then click Set Project.
  7. A warning screen explains the effects of changing the Cloud Platform project. Read the notice carefully, and click Confirm.

Google Cloud projects & shared drives

Shared drives (formerly Team Drives) provide shared spaces where groups of Drive users can collaborate on Apps Script projects and Drive documents. Shared drives are valuable when developing scripts, add-ons, and web apps with a team, but they place some restrictions on what you can do with older default Google Cloud projects.

The following list of restrictions describes how Google Cloud projects interact with shared drives:

  • If your script project uses a standard project, there are no additional restrictions when the script project resides in a shared drive.
  • If your script project uses a default project that was created on or after April 8, 2019, there are no additional restrictions when the script project resides in a shared drive.
  • If your script project uses a default project that was created before April 8, 2019, the following restrictions apply while the script project resides on a shared drive:
    1. You can't access the default project using the Apps Script UI or the Google Cloud console. This restriction prevents you from taking actions that require direct access to the project.
    2. You can't activate advanced services. To activate advanced services, switch to a standard project.
    3. When you move an existing Apps Script project into a shared drive, Google restricts access to the default Google Cloud project. You can still access the default project if you had access prior to the move. For example, if you created a script in your My Drive folder and then moved it into a shared drive, you could still access the script's Google Cloud project. Your collaborators in the shared drive might not be able to.
    4. A script retains the Google Cloud project name it had prior to being moved to a shared drive. Even if you change the project name on the shared drive, users that authorize the script still see the old name on authorization dialogs.

To avoid the above restrictions for older scripts, switch to a standard project.

Get a list of Apps Script Google Cloud projects

If you have the resourcemanager.projects.list permission for your organization's Apps Script Project folder, you can view all of the standard and default Apps Script Google Cloud projects within the folder.

  1. Open the Google Cloud console Manage Resources page.
  2. Next to the Apps Script folder, copy the ID.
  3. Click Filter > Parent ID and paste the Apps Script folder ID.

Delete Apps Script Google Cloud projects

To delete an Apps Script Google Cloud project, follow the steps under Get a list of Apps Script Google Cloud projects, select the project you want to delete and click Delete.

To delete an Apps Script project using gcloud, use the following commands.

gcloud projects list --filter='parent.id=APPS_SCRIPT_FOLDER_ID'
gcloud projects delete PROJECT_ID

For more information about deleting Google Cloud projects, see Shutting down (deleting) projects.