Repository permissions and access on CloudBees CodeShip

How permissions work on CloudBees CodeShip

Let’s take a look at how CodeShip manages permissions around your source control, your builds and your team.

What do we mean by permissions?

When we say permissions, we are talking about access you give CodeShip to your source control repo, or access you give to people on your team to your CodeShip builds and account information.

Repository permissions vs. Access permissions

In terms of access you give CodeShip, there are two different types that are in play: repository level permissions (for setting up new projects on CodeShip) and access level permissions (for authenticating with an SCM instead of username/password).

To configure CodeShip with your Bitbucket or Gitlab repository correctly, the account that connects a repository needs to have the necessary permissions to setup a webhook, add deploy keys, update commit statuses, as well as clone the code in your repositories. For the initial configuration of CodeShip, we expect the user’s account to have admin permissions (or master or owner depending on your source control system) to allow us to properly configure your SCM. In case a user will not need to setup new projects on CodeShip, we mainly need to

Github works slightly different, and requires that you to install the Github App first, and then allow the app access to the repositories you want to use on CodeShip. You can select only the repositories you want us to have access to, or all repositories (incl. future ones). We suggest you only allow access to specific repositories to keep control on who can access what. For you to setup the github app, you must have permission to install apps on your organization and configure them. Once the app has been installed, users who setup new projects mainly need to have access to the repository, but do not need permission to install apps.

As for access level permissions, we aim to request as few permissions as possible for users, but for some SCMs this is not possible, yet. Github is an example where we only ask for permissions to authenticate the user as well as the email, where as Gitlab only lets us ask for access to everything.

The next section explains which specific permissions we ask for, depending on your source control system.

What permissions are needed on my source control?

As mentioned above, CodeShip requires both repository and access level permissions. Depending on the source control service being used, these are called something different:


  • For setting up a new project (repository level permissions), we need the CodeShip Github App installed on your Github organization, and access to the necessary repositories via that app. We’ll help you set things up when you create your first project, and once the app is installed you only need to make sure it has access to the repository you want to use in your new project.

  • The CodeShip Github App will ask for permissions to:

    • Read your code

    • Read metadata for your organization (default permission set by Github)

    • Read and Write access to administer your project and set commit status (this is a combined permission, without it we can’t update commit status)

  • For regular user access, aside from the default access, we only ask to read your email, in case we need to get in contact with you

    • The default permissions mainly allows us to see what resources you have access to (e.g. which organizations you’re connected to, and if they have the CodeShip app installed). We cannot change these permissions as they’re controlled by Github


  • For setting up a new project (repository level permissions), we need the account to have master or owner permissions.

  • For regular access, we currently ask for full access to everything in the repository. In the future we plan to reduce this to only cover reading/writing to your repos and webhooks as well as reading your email addresses (more specifically repository:write, email, and webhook). You can see the full list of permission options available from BitBucket here.


  • For setting up a new project (repository level permissions), we need the account to have admin permissions.

  • For regular access, GitLab only offers one option (the api scope), which unfortunately gives us access to everything on the repo. We wish it was different, but as of now, GitLab only provides two options where only one will allow us to access your repos.

What permissions can I assign my team members?

You can learn more about organization management on CodeShip in the Organization accounts documentation, but in summary there are four basic security levels for teams on CodeShip:

  • Owners have control over all aspects of an organization. From changing the subscription to managing organization projects and teams.

  • Managers have control over team and project management of an organization. They can add and remove projects and manage the organization teams by adding new team members or assigning projects to teams. They have access to all projects and are able to change the project configuration.

  • Project Managers can manage projects the team is assigned to. They can debug builds, update test settings, or manage deployments.

  • Contributors have read-only access to their projects. This means that they can view the project dashboard and build details but are not allowed to change project settings or open debug builds.

"3rd Party Access Restrictions" For Organizations

Note this only applies to GitHub.

If the repositories for a GitHub organization don’t show up on CodeShip, please head over to the settings for the CodeShip application on GitHub and in the section labeled Organization access either

  • Request access if you are not an administrator for the organization. (Your request will then have to be approved by an admin.)

  • Grant access if you are an administrator.

Once this is done and access has been granted, the organizations repositories will show up in the repository selector on CodeShip again.

See GitHub’s help article on 3rd party restrictions for more background information about this feature.

What if I’m not an admin of the repo?

If you attempt to connect a repository to a new project, and you don’t have admin permissions on that repository (or, for Github don’t have permission to install the CodeShip Github App), there are two things you can do:

  1. The simplest option is to get admin permissions to the repo, which can be given to the team you’re in or specifically to your user

  2. (Non Github): The second option is to have someone else, who have admin permissions, setup the project for you. The flow would look like this:

    1. User with admin permission creates the project and connects the repo (CodeShip will create a webhook and register an SSH key)

    2. Same user changes the project settings (Project settings > General > Account used for authentication) and assigns the project to you or another user with limited permissions

    3. The project can now be used by CodeShip, even without having admin permissions to the repo

  3. (Github Only): you can get a user with sufficient rights to install the CodeShip Github App and provide it access to the repositories you need, and then proceed to setup the new projects. During the setup the app will retrieve the repositories available to it and you can select the one you want for your new project


You can learn more about security on CodeShip in the Security documentation.

Can CodeShip staff see my code or builds?

There are two CodeShip services, and staff have different levels of access for each:

  • On CloudBees CodeShip Basic, with your permission, our support team can open an SSH debug session into your build machine, which allows us to see your source code.

  • On CloudBees CodeShip Pro, we have no direct access to your source control, but our support team can see your builds and build logs, as well as account information.