Table of Contents
Organizations allow you to manage access to a shared group of applications across your development team. The development experience remains largely the same, but you now have access to more granular roles and can more efficiently manage your development process.
Organization Accounts are currently only available for purchase through our sales channel. Contact us if you would like to purchase an Organization Account.
Once your org is provisioned, you will receive an email from Heroku with the org name, resource limits and a link to your dashboard. This guide outlines how to complete the setup of your org.
When an organization is provisioned it only has a single user - the admin user that requested the org. It is up to this initial admin to add other users to the org and give them the appropriate access.
Organizations access is partitioned across three distinct roles: Admin, member and collaborator.
An admin user controls membership to the org, can view billing information, and can perform high-level lifecycle actions like locking an app to prevent additional access. The admin role is often given to those in the organization that are responsible for the development process, such as engineering or team leads.
The member role allows a user to create apps within, and transfer apps to, an org, and perform common development tasks like deploying and scaling the app. The member role is commonly assigned to the in-house developers working on your applications.
Collaborators are a more limited case of a member in that they can deploy and develop against only specific applications – not all the apps within the org. Give collaborator access to users that you only want manipulating specific apps. Contract developers assigned to a specific project are a good example of the collaborator role.
Users can be managed from the Access tab in your org Dashboard.
You can also manage users using the Heroku CLI. Add a new org member with:
$ heroku members:add email@example.com --org acme-widgets Adding firstname.lastname@example.org as member to organization acme-widgets... done
Add additional admin users using the same command with the
$ heroku members:add email@example.com --org acme-widgets --role admin Adding firstname.lastname@example.org as admin to organization acme-widgets... done
Because of their app-level access, collaborators are a special case and require a different command.
$ heroku sharing:add email@example.com --app acme-website Adding firstname.lastname@example.org to acme-website as collaborator... done
Applications become part of an organization in one of two ways – by being transferred into the org or by being created as part of the org.
It is common for existing development teams to have several apps already in development under each developer’s personal account or even a shared personal account. The owner of these apps must transfer in their app to the org before it can be managed as part of the org. Otherwise the individual app owners will continue to be billed for them using their personal billing details.
To transfer an application, the current app owner must select the app to transfer from their Dashboard, then go to the Settings pane and use the transfer drop-down at the bottom of the settings page:
You can also import applications in bulk from your personal account to an organization that you are a member of. To import multiple applications, select the Import app icon at the bottom of the apps list of your org Dashboard, select the apps that you want to move into the organization, and confirm your choice(s):
You can also use the CLI to transfer apps into an organization:
$ heroku sharing:transfer acme-widgets -a deep-spring-4274 Transferring deep-spring-4274 to acme-widgets... done
When starting a new project, org admin and member users can create an app directly within the org.
From the org dashboard, select ‘Create a new app’ at the bottom of the apps list.
Or, from the CLI, specify the org with the
--org flag on the
heroku create command.
$ heroku create --org acme-inc Creating frozen-wave-4030 in organization acme-inc...done, stack is cedar http://frozen-wave-4030.herokuapp.com/ | email@example.com:frozen-wave-4030.git Git remote heroku added
Applications can be removed from an org by transferring them to a new owner.
To transfer an application, a current org admin must select the app to transfer from their Dashboard, then go to the Settings pane and use the transfer drop-down at the bottom of the settings page:
You can also use the CLI to transfer apps out of an organization:
$ heroku sharing:transfer firstname.lastname@example.org --app acme-website-staging Transferring acme-website-staging to email@example.com... done
Org admins have access to the Usage tab in Dashboard. From there, you can see your current resource usage against package limits as well as historical usage.
At this stage your org should be populated with an initial list of applications and users, and your development team should be able to deploy and manage the apps using the standard Heroku workflow and tools. Your developers will benefit from reading the guide on developing apps within an org, which describes how to efficiently work within an organization account.
Beyond the basic steps described in this guide, there is also a detailed doc that covers the administration of org users and application access.