Working with shared projects

Project sharing allows project owners to share their AWS CodeBuild projects with other AWS 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 AWS 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 AWS CodeBuild.

Related services

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

For more information, see the AWS RAM User Guide.

Sharing a project

The consumer can use both the AWS CLI and AWS 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 AWS 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 AWS Organizations. For more information, see Enable sharing with AWS Organizations in the AWS RAM User Guide.

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

To share a project that you own (CodeBuild console)

1. Open the AWS CodeBuild console at https://console.aws.amazon.com/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 AWS RAM User Guide.

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

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

To share a project that you own (AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS CodeBuild console, AWS RAM console, or AWS CLI to do this.

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

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

To unshare a shared project that you own (AWS 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 AWS CLI to identify shared projects.

To identify projects shared with your AWS account or user (AWS 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.