Working with shared projects - Amazon CodeBuild
Prerequisites for sharing projectsPrerequisites for accessing shared projectsRelated servicesSharing a projectUnsharing a shared projectIdentifying a shared projectShared project permissions
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Working with shared projects

Project sharing allows project owners to share their Amazon CodeBuild projects with other Amazon accounts or users. In this model, the account that owns the project (owner) shares a project with other accounts (consumers). A consumer cannot edit or run a project.

Prerequisites for sharing projects

To share a project, your Amazon account must own it. You cannot share a project that has been shared with you.

Prerequisites for accessing shared projects shared with you

To access a shared project, a consumer's IAM role requires the BatchGetProjects permission. You can attach the following policy to their IAM role: 

{
    "Effect": "Allow",
    "Resource": [
        "*"
    ],
    "Action": [
        "codebuild:BatchGetProjects"
    ]
}

For more information, see Using identity-based policies for Amazon CodeBuild.

Project sharing integrates with Amazon Resource Access Manager (Amazon RAM), a service that makes it possible for you to share your Amazon resources with any Amazon account or through Amazon Organizations. With Amazon RAM, you share resources by creating a resource share that specifies the resources and the consumers to share them with. Consumers can be individual Amazon accounts, organizational units in Amazon Organizations, or an entire organization in Amazon Organizations.

For more information, see the Amazon RAM User Guide.

Sharing a project

The consumer can use both the Amazon CLI and Amazon CodeBuild console to view the project and builds you've shared. The consumer cannot edit or run the project.

You can add a project to an existing resource share or you can create one in the Amazon RAM console.

Note

You cannot delete a project with builds that has been added to a resource share.

To share a project with organizational units or an entire organization, you must enable sharing with Amazon Organizations. For more information, see Enable sharing with Amazon Organizations in the Amazon RAM User Guide.

You can use the Amazon CodeBuild console, Amazon RAM console, or the Amazon CLI to share a project that you own.

To share a project that you own (CodeBuild console)

  1. Open the Amazon CodeBuild console at https://console.amazonaws.cn/codesuite/codebuild/home.

  2. In the navigation pane, choose Build projects.

    Note

    By default, only the 10 most recent build projects are displayed. To view more build projects, choose the gear icon, and then choose a different value for Projects per page or use the back and forward arrows.

  3. Choose the project you want to share, and then choose Share. For more information, see Create a resource share in the Amazon RAM User Guide.

To share a project that you own (Amazon RAM console)

See Creating a resource share in the Amazon RAM User Guide.

To share a project that you own (Amazon RAM command)

Use the create-resource-share command.

To share a project that you own (CodeBuild command)

Use the put-resource-policy command:

  1. Create a file named policy.json and copy the following into it. 

    {
  "Version":"2012-10-17",
  "Statement":[{
    "Effect":"Allow",
    "Principal":{
      "AWS":"<consumer-aws-account-id-or-user>"
    },
    "Action":[
      "codebuild:BatchGetProjects",
      "codebuild:BatchGetBuilds",
      "codebuild:ListBuildsForProject"],
    "Resource":"<arn-of-project-to-share>"
  }]
}

  2. Update policy.json with the project ARN and identifiers to share it with. The following example grants read-only access to the root user for the Amazon account identified by 123456789012. 

    {
  "Version":"2012-10-17",
  "Statement":[{
    "Effect":"Allow",
    "Principal":{
      "AWS": [
        "123456789012"
      ]
    },
    "Action":[
      "codebuild:BatchGetProjects",
      "codebuild:BatchGetBuilds",
      "codebuild:ListBuildsForProject"],
    "Resource":"arn:aws:codebuild:us-west-2:123456789012:project/my-project"
  }]
}

  3. Run the put-resource-policy command.

    aws codebuild put-resource-policy --resource-arn <project-arn> --policy file://policy.json

  4. Get the Amazon RAM resource share ARN.

    aws ram list-resources --resource-owner SELF --resource-arns <project-arn>

    This will return a response similar to this:

    {
  "resources": [
    {
      "arn": "<project-arn>",
      "type": "<type>",
      "resourceShareArn": "<resource-share-arn>",
      "creationTime": "<creation-time>",
      "lastUpdatedTime": "<last-update-time>"
    }
  ]
}

    From the response, copy the <resource-share-arn> value to use in the next step.

  5. Run the Amazon RAM promote-resource-share-created-from-policy command.

    aws ram promote-resource-share-created-from-policy --resource-share-arn <resource-share-arn>

Unsharing a shared project

An unshared project, including its builds, can be accessed only by its owner. If you unshare a project, any Amazon account or user you previously shared it with cannot access the project or its builds.

To unshare a shared project that you own, you must remove it from the resource share. You can use the Amazon CodeBuild console, Amazon RAM console, or Amazon CLI to do this.

To unshare a shared project that you own (Amazon RAM console)

See Updating a resource share in the Amazon RAM User Guide.

To unshare a shared project that you own (Amazon CLI)

Use the disassociate-resource-share command.

To unshare project that you own (CodeBuild command)

Run the delete-resource-policy command and specify the ARN of the project you want to unshare:

aws codebuild delete-resource-policy --resource-arn project-arn

Identifying a shared project

Owners and consumers can use the Amazon CLI to identify shared projects.

To identify projects shared with your Amazon account or user (Amazon CLI)

Use the list-shared-projects command to return the projects that are shared with you.

Shared project permissions

Permissions for owners

A project owner can edit the project and use it to run builds.

Permissions for consumers

A project consumer can view a project and its builds, but cannot edit a project or use it to run builds.