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.
This feature is currently available in Heroku Enterprise
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.
For fine-grained access controls, see Using App privileges in Heroku Organizations
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
Two-factor authentication is a Heroku platform security feature. When an user enables 2FA on their account, they are required to log on with a verification code in addition to their username and password, for additional security.
Users can enable and disable 2FA on their individual accounts. When these users are part of an organization, admins and other members of the org need visibility into their 2FA status. This helps ensure continuous compliance with security and governance policies.
The Access page of an organization highlights users who have either never enabled or have currently disabled two-factor authentication for their Heroku accounts. The status is updated as soon as it changes.
On seeing users with two-factor authentication disabled, admins of the org may choose to ensure compliance and maintain their security composure by removing those users from the org, changing their role or leaving them as collaborators only on specific less-sensitive apps.
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 first select Personal Apps on the sidebar and then drag and drop an app from the listed apps onto the destination org also shown on the sidebar:
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
Another way to transfer apps is from the app settings page:
When starting a new project, org admin and member users can create an app directly within the org.
First pick the org from the side bar. Then click the plus sign on the top right corner to create a new app in the org.
Or, from the CLI, specify the org with the
--org flag on the
heroku create command.
$ heroku create --org acme-widgets Creating frozen-wave-4030 in organization acme-widgets...done, stack is cedar-14 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 or by deleting them. Only admins can delete or transfer applications.
To transfer an application, a current org admin must select the app to transfer from the Apps page, then go to the Settings pane and use the transfer drop-down at the bottom of the settings page. Admins can transfer apps to their own personal account or to another organization for which they have an admin role. Only these options are shown in the drop down.
You can also use the CLI to transfer apps out of an organization. Using this method, you can also transfer an app to other admins of the org instead of just yourself:
$ heroku sharing:transfer firstname.lastname@example.org --app acme-website-ui Transferring acme-website-ui to email@example.com... done
Admins and members can inspect the current resource usage, and corresponding charges, of all apps in the org by going to the org’s Resources page. This page is accessed by clicking on “Resources” under the org in the sidebar. An up-to-date report is displayed.
The report shows the current monthly charge for each app and the total estimated monthly charges for all apps in the org. A count of development and production apps is also presented; a production app is any app that has more than 1 dyno at the time the report is generated.
You can drill down into the resource usage of each app by expanding the listed apps and get a breakdown of charges for dynos and each add-on used by the app.
Org admins have access to the Usage page in Dashboard. A menu entry for the Usage page appears on the sidebar under orgs which were provisioned as part of a package of dynos and add-ons credits. For such orgs, you can see your current resource usage against package limits as well as historical usage by navigating to the Usage page.
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.