Skip to main content
Welcome — in this lesson we’ll demystify the Project Identification Framework in Google Cloud Platform (GCP). Think of this framework as a project’s passport: a set of identifiers that let both you and Google know exactly which project you’re referring to. Clear identifiers prevent confusion when managing resources, billing, APIs, and automation. This guide breaks the framework down step by step, with practical examples and commands so you can use the correct identifier in the right context.

​
The three project identifiers

GCP projects expose three distinct identifiers: the project name, the project ID, and the project number. Each serves a different purpose.
IdentifierDescriptionMutabilityTypical uses
Project nameHuman-readable label shown in the Console and UIs.Mutable (renameable)Console displays, dashboards, documentation
Project IDGlobally unique string identifier. Must match naming rules (6–30 chars, lowercase letters, digits, hyphens; begins with a letter; ends with a letter or digit).ImmutableResource paths (e.g. projects/{PROJECT_ID}), scripts, URLs, many APIs
Project numberNumeric identifier generated by Google Cloud.ImmutableInternal APIs, billing, quotas, some backend systems
Use the project name for human-readability; use the project ID for resource paths, scripts, and most automations; and be aware that Google services often reference the project number for billing and internal links.
Project IDs and project numbers are immutable. Choose project IDs carefully — once created they cannot be changed.

​
Identifier details and rules

  • Project name
    • Free-text, intended for people. It can contain spaces and punctuation.
    • Changeable at any time without affecting resource references.
  • Project ID
    • Globally unique across GCP.
    • Naming rules: 6–30 characters, lowercase letters (a–z), digits (0–9), and hyphens (-); must begin with a letter and end with a letter or digit.
    • Used in resource identifiers such as projects/{PROJECT_ID} (wrap the placeholder in backticks when documenting).
  • Project number
    • A numeric, Google-assigned identifier (e.g., 123456789012).
    • Frequently used behind the scenes for billing, quotas, and Google-managed integrations.

​
How these identifiers are used

  • Resource names and many APIs use the project ID in paths, for example: projects/{PROJECT_ID}
  • Some APIs, billing connectors, and quota systems prefer or require the project number. A few APIs accept either the project ID or project number.
  • IAM and resource-level permissions often reference the project ID in role bindings and policy documents; internal links and system accounts may use the project number.
Because usage varies by API and service, prefer the project ID for automation and scripts, but check the API documentation if you suspect the project number is required.

​
Common use-case mapping

Use casePreferReason
Automation scripts, CI/CD, IaCProject IDGlobally unique and stable
Billing exports, quotas, some backend APIsProject numberInternally referenced by Google
Console display, human communicationProject nameReadable and editable

​
Examples and gcloud commands

  • Create a new project:
gcloud projects create my-project-id --name="My Project"
  • Retrieve identifiers for a project:
gcloud projects describe my-project-id --format="value(projectNumber,projectId,name)"
  • List projects with key fields:
gcloud projects list --format="table(projectId, projectNumber, name)"
These commands display the human name, immutable project ID, and numeric project number.

​
Best practices

  • Adopt a standardized naming convention for project names and project IDs. Typical components include organization, environment (dev/stage/prod), team, and application shorthand.
    • Example:
      • name: “Acme Analytics — Prod”
      • project-id: acme-analytics-prod
  • Keep project IDs short, descriptive, and free of sensitive information (avoid embedding passwords, personal data, or secret keys).
  • Use the project ID in scripts, IaC (Terraform, Deployment Manager), and CI/CD pipelines because it is stable and globally unique.
  • Avoid personal or ephemeral identifiers in a project ID because it cannot be changed later.
Example naming pattern table:
Pattern partExample
Organizationacme
Applicationanalytics
Environmentprod
Combined project IDacme-analytics-prod

​
When to check API docs

Some APIs accept either the projectId or projectNumber; others require the numeric project number. If you see an API parameter like parent or name that references a project, consult that API’s documentation to confirm which identifier is accepted. Always prefer the project ID in automation unless the docs explicitly require the project number.

​
Summary

  • GCP projects expose three identifiers: a mutable human-readable name, an immutable globally unique project ID (string), and an immutable numeric project number.
  • Use the project name for display, the project ID for scripts and resource paths, and be aware that Google services sometimes require the project number.
  • Follow consistent naming conventions and avoid embedding sensitive information in project IDs.
A recommended follow-up topic: GCP networking concepts — learning how projects and resources connect across Virtual Private Cloud (VPC), Shared VPCs, and inter-project networking will deepen your understanding of resource architectures.

Watch Video