Create a Secure Source Manager instance

Secure Source Manager is a single-tenant service. A single Secure Source Manager instance should only include users from one Google Cloud customer unless multiple companies who have a contractual relationship need to use a single instance for collaboration.

If you are working with multiple companies and want to collaborate around source with each of them, we recommend creating a separate instance for each company.

To create an instance with VPC Service Controls enabled, see Configure Secure Source Manager in a VPC Service Controls perimeter.

Before you begin

  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Enable the Secure Source Manager API.

    Enable the API

  4. Install the Google Cloud CLI.

  5. To initialize the gcloud CLI, run the following command: 

    gcloud init
    6.

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  7. Enable the Secure Source Manager API.

    Enable the API

  8. Install the Google Cloud CLI.

  9. To initialize the gcloud CLI, run the following command: 

    gcloud init
    10.
  10. Install the `beta` Google Cloud CLI component: 
    gcloud components install beta

Required roles

To get the permissions that you need to create a Secure Source Manager instance, ask your administrator to grant you the Secure Source Manager Instance Owner (roles/securesourcemanager.instanceOwner) IAM role on the Google Cloud project.

Secure Source Manager roles don't appear in the Google Cloud console until they have been granted to a principal. To grant a Secure Source Manager role for the first time, see Grant and revoke IAM roles.

Data encryption

By default, Google Cloud automatically encrypts data at rest using encryption keys managed by Google. If you have specific compliance or regulatory requirements related to the keys that protect your data, you can create Secure Source Manager instances encrypted with customer-managed encryption keys (CMEK).

Don't store sensitive data in instance IDs or label key-value pairs as they are not encrypted with CMEK.

If you are creating your first Secure Source Manager instance in your project, you will need to manually create the Secure Source Manager service agent by running the following command:

gcloud beta services identity create \
    --service=securesourcemanager.googleapis.com \
    --project=PROJECT_ID

Where PROJECT_ID is the project ID of the project where you will create your Secure Source Manager instance.

Create an instance

To create an instance:

gcloud CLI

  1. Run the following command to create an instance. You might be asked to authenticate to the gcloud CLI.

    gcloud beta source-manager instances create INSTANCE_ID \
    --region=LOCATION \
    --project=PROJECT_ID \
    --kms-key=projects/KEY_PROJECT/locations/KEY_LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY

    Where:

    • INSTANCE_ID is the name of the instance you want to create.
    • LOCATION is the region where you want to create the instance. For information on supported locations, see Locations.
    • PROJECT_ID is the project ID of the project you want to create an instance in.
    • -kms-key is an optional flag. Include if you want to use your own customer-managed encryption key (CMEK) to create the instance. CMEK keys must be in the same location that you are creating your instance in, but can be in a different project. Omit this flag if you want to use Google default encryption. If you want to encrypt your data using CMEK, replace the following:
      • KEY_PROJECT with the project you created your key in.
      • KEY_LOCATION with location of the key.
      • KEYRING_NAME with the name of your key ring.
      • KEY with the name of your key.

    A long-running create instance operation starts. The output looks like the following:

    Create request issued for [my-instance].
done: false
metadata:
  '@type': type.googleapis.com/google.cloud.securesourcemanager.v1.OperationMetadata
  apiVersion: v1
  createTime: '2023-02-27T20:57:52.315609549Z'
  requestedCancellation: false
  target: projects/my-project/locations/us-central1/instances/my-instance
  verb: create
name: projects/my-project/locations/us-central1/operations/operation-1234567894561-5ec69948c0f2b-60dd727f-a9b97a2e

    Where projects/my-project/locations/us-central1/operations/operation-1234567894561-5ec69948c0f2b-60dd727f-a9b97a2e is the OPERATION_NAME.

    It takes up to 60 minutes to create the instance.

  2. Note the OPERATION_NAME as you will need to use it to check the status of the operation.

  3. Check the status of the create operation by running the following command:

    gcloud beta source-manager operations describe OPERATION_NAME \
    --region=LOCATION

    Replace the following:

    • OPERATION_NAME with the operation name from your create command response.
    • LOCATION with the region where you want to create the instance. For information on supported locations, see Locations.

    Once the instance is ready, the response will look similar to the following:

    {
"name": "projects/my-project/locations/us-central1/operations/operation-123456789012-5ec69948c0f2b-60dd727f-a9b97a2e",
"metadata": {
  "@type": "type.googleapis.com/google.cloud.securesourcemanager.v1.OperationMetadata",
  "createTime": "2022-11-01T14:31:32.420469714Z",
  "endTime": "2022-11-01T14:48:34.140378114Z",
  "target": "projects/my-project/locations/us-central1/instances/test",
  "verb": "create",
  "requestedCancellation": false,
  "apiVersion": "v1"
},
"done": true,
"response": {
  "@type": "type.googleapis.com/google.cloud.securesourcemanager.v1.Instance",
  "name": "projects/my-project/locations/us-central1/instances/test",
  "createTime": "2022-11-01T14:31:32.416413630Z",
  "updateTime": "2022-11-01T14:31:32.416413630Z",
  "labels": {
    "ldap": "user",
    "source": "manual"
  },
  "state": "ACTIVE",
  "hostConfig": {
    "html": "test-098765432109.us-central1.sourcemanager.dev",
    "api": "test-098765432109-api.us-central1.sourcemanager.dev",
    "gitHttp": "test-098765432109-git.us-central1.sourcemanager.dev"
  }
}
}

    Where the test-098765432109.us-central1.sourcemanager.dev is the instance HTML URL.

  4. Copy the HTML URL from the successfully created check status command. You will need this URL to access the instance though its web interface.

API

  1. Run the following command to create an instance. You might be asked to authenticate to the gcloud CLI.

    curl \
    -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://securesourcemanager.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?instance_id=INSTANCE_ID \
    -H "Content-Type: application/json" \
    -d '{ "kms_key":"projects/KEY_PROJECT/locations/KEY_LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY"}'

    Where:

    • INSTANCE_ID is the name of the instance you want to create.
    • LOCATION is the region where you want to create the instance. For information on supported locations, see Locations.
    • PROJECT_ID is the project ID of the project you want to create an instance in.
    • -d is an optional HTTP POST data flag that can be used to specify a CMEK key to encrypt your instance. Omit this flag if you want to use the default Google encryption. If you want to encrypt your data using CMEK, replace the following:
      • KEY_PROJECT with the project you created your key in.
      • KEY_LOCATION with location of the key.
      • KEYRING_NAME with the name of your key ring.
      • KEY with the name of your key.

    A long-running create instance operation starts. The output looks like the following:

    {
"name": "projects/my-project/locations/us-central1/operations/operation-1234567894561-5ec69948c0f2b-60dd727f-a9b97a2e",
"metadata": {
  "@type": "type.googleapis.com/google.cloud.securesourcemanager.v1.OperationMetadata",
  "createTime": "2022-11-01T14:31:32.420469714Z",
  "target": "projects/my-project/locations/us-central1/instances/test",
  "verb": "create",
  "requestedCancellation": false,
  "apiVersion": "v1"
},
"done": false
}

    Where projects/my-project/locations/us-central1/operations/operation-1234567894561-5ec69948c0f2b-60dd727f-a9b97a2e is the OPERATION_NAME.

    It takes up to 60 minutes to create the instance.

  2. Copy the OPERATION_NAME.

  3. Check the status of the create operation by running the following command:

    curl \
    -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://securesourcemanager.googleapis.com/v1/OPERATION_NAME

    Where OPERATION_NAME is the operation name from the response to your create command.

    Once the instance is ready, the response will look similar to the following:

    {
"name": "projects/my-project/locations/us-central1/operations/operation-123456789012-5ec69948c0f2b-60dd727f-a9b97a2e",
"metadata": {
  "@type": "type.googleapis.com/google.cloud.securesourcemanager.v1.OperationMetadata",
  "createTime": "2022-11-01T14:31:32.420469714Z",
  "endTime": "2022-11-01T14:48:34.140378114Z",
  "target": "projects/my-project/locations/us-central1/instances/test",
  "verb": "create",
  "requestedCancellation": false,
  "apiVersion": "v1"
},
"done": true,
"response": {
  "@type": "type.googleapis.com/google.cloud.securesourcemanager.v1.Instance",
  "name": "projects/my-project/locations/us-central1/instances/test",
  "createTime": "2022-11-01T14:31:32.416413630Z",
  "updateTime": "2022-11-01T14:31:32.416413630Z",
  "labels": {
    "ldap": "user",
    "source": "manual"
  },
  "state": "ACTIVE",
  "hostConfig": {
    "html": "test-098765432109.us-central1.sourcemanager.dev",
    "api": "test-098765432109-api.us-central1.sourcemanager.dev",
    "gitHttp": "test-098765432109-git.us-central1.sourcemanager.dev"
  }
}
}

    Where the test-098765432109.us-central1.sourcemanager.dev is the instance HTML URL.

  4. Copy the HTML URL from the successfully created check status command. You will need this URL to access the instance through its web interface.

Access an instance

After the instance is created, you can access it through its web interface using a browser.

To create repositories in the instance you need the Repo Creator role (roles/securesourcemanager.repoCreator) on the instance project and the Instance Repository Creator role (roles/securesourcemanager.instanceRepositoryCreator) on the Secure Source Manager instance.

  1. Copy the HTML URL from the successfully created check status command into your browser address bar. If you don't have the URL, you can run the check status command given in the create an instance section again.
  2. An OAuth screen appears asking if you want to give sourcemanager.dev access to your Google Account.
  3. Click the Allow button.
  4. The Secure Source Manager web interface opens. You can create and view repositories and all associated issues and pull requests from the web interface.

What's next