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 that you intend to publish.

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 Cloud project your script uses early in development. Switching later can cause complications, like requiring your users to re-authorize.

Default Cloud projects

When you create an Apps Script project, Apps Script creates a default 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 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 Cloud project. For example, to view Google Cloud logs in the Google Cloud console, your script must use a standard project.

By default, Cloud projects have an Identity and Access Management (IAM) policy with one entry, a Google service account that acts as the owner of the default project. The Google service account is appsdev-apps-dev-script-auth@system.gserviceaccount.com.

View or update default Cloud projects

Most users can’t directly locate, view, or edit default projects in the Google Cloud console. If you're an Admin, refer to View default Google Cloud projects.

If you created your script project before April 8, 2019, you might use a default project that you can access in the Google Cloud console. To access the default project, go to the script project's settings and click the project number.

Delete default Cloud projects

If you're an admin, you can delete default Cloud projects like you would standard Cloud projects. See Delete Apps Script 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 Cloud projects

Default 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 Cloud projects

You must use a standard project in the following situations:

Standard 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 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 Cloud project name is used to identify the script (not the script project name). For this reason, be sure to set an appropriate Cloud project name.

Access a standard Cloud project

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

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

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

Activate an API in a standard Cloud project

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

  1. Open the 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 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 Cloud project

All 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 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 Google 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 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 Cloud projects create a consent screen automatically from the Apps Script project details; you can't adjust those settings. Standard Cloud projects let you customize this information. You can configure your script's consent screen by doing the following:

  1. Open the 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 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 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 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 Cloud project. You can add individual emails, Google Groups, or domains as new members.
  6. Click Save.

Group multiple scripts with a single Cloud project

You can have multiple Apps Script projects share the same standard 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.

Use a different standard Cloud project

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

Effects of switching to a different standard Cloud project

If you switch your script from a default project or to a different standard project, it has the following effects:

  • If you activated advanced services for your script, you must turn on the corresponding APIs in the new Cloud project. You lose any data tied to the advanced services in the previous Cloud project. To learn how to turn on APIs in your Cloud project, refer to Enable Google Workspace APIs.
  • If your script uses the built-in Google Drive service, you must turn on the Drive API in standard Cloud projects.

    In your standard Cloud project, turn on the Drive API:

    Turn on the Drive API

  • All users who have previously authorized the script must re-authorize. In most cases, all users who have previously authorized apps associated with the new project must also re-authorize.
  • If your script is associated with an app listing on the Google Workspace Marketplace, your app listing, users, and reviews don't carry over to the new project. You must create an app listing within the new project and your users must reinstall your app. For information about creating a new app listing, refer to Publish an app.
  • You can't switch a script back to a default project. Apps Script deletes default projects after you set the script to use a standard project.

Switch to a different standard Cloud project

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

  1. If you don't have a suitable 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 the Project Browser and OAuth Config Editor roles, or roles with the equivalent permissions, for the project. You can't use a project that was automatically created by Apps Script.
  3. Determine the Project number of your Cloud project.
  4. Open the script whose 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.

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 Cloud projects.

The following list of restrictions describes how 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 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 Cloud project. Your collaborators in the shared drive might not be able to.
    4. A script retains the 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 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 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 Cloud projects

To delete an Apps Script Cloud project, follow the steps under Get a list of Apps Script 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 Cloud projects, see Shutting down (deleting) projects.