Skip to main content

Profile Registries

Sharing consistent AWS profiles amongst team members can be helpful. This allows you to adopt consistent role names across your documentation and scripts. For example: ”run your development deploys using the cf-dev role”.

To manage sharing profile configuration, Granted provides a Profile Registry. This feature utilizes a git repository as a central store for AWS profile configurations. Granted's Profile Registry synchronizes this to the default AWS config file located locally at ~/.aws/config.

Creating a Profile Registry

Using Granted to configure a Profile Registry

Create a Profile Registry folder.

You can quickly copy the contents of your local ~/.aws/config file to a Profile Registry repository with the following command:

granted registry setup

This will copy all profiles inside your ~/.aws/config file to the Profile Registry's config file.

This command outputs a granted-registry folder to your current working directory. This folder contains the following files:

├── .git
├── config
└── granted.yml

Add the local repository to your git-based version control tool.

The granted-registry repository will need to be manually added to your organization's version control tool. For GitHub, you can follow this link.

Adding a Profile Registry

You can add any git-based repository to Granted's Profile Registry. By default, Granted looks for a granted.yml file in the root of the repository. Should you wish to specify an alternative YAML file, follow this guide.

You can add a repository to Granted's Profile Registry by running the following command:

granted registry add <your-repo-git-url>

The granted.yml file identifies AWS config files to be synced to Granted's Profile Registry. These config files must exist in the repository; paths pointing outside the repository such as ../config are not permitted. Multiple config files are allowed and are merged together when syncing your local config file to the repository.

A valid granted.yml requires an awsConfig key to be present. For example:

- ./config
- ./other-config

In the above example, AWS profiles inside config and other-config files will be merged and synced to your local ./aws/config file.


If there are any duplicate profile names in the same repository, the latter will overwrite those former causing only unique profiles to be synced.

Adding a registry will manipulate your local /.aws/config file to include Granted autogenerated sections. Here's an example:

# Granted-Registry Autogenerated Section. DO NOT EDIT.
# This section is automatically generated by Granted ( Manual edits to this section will be overwritten.
# To edit, clone your profile registry repo, edit granted.yml, and push your changes. You may need to make a pull request depending on the repository settings.
# To stop syncing and remove this section, run 'granted registry remove

[profile dev]
sso_start_url = <>
sso_region = <your-sso-region>
sso_account_id = <your-sso-account-id>
sso_role_name = <your-sso-role-name>


To avoid confusion, synced profiles are placed into a designated region in the /.aws/config file as shown above. This allows users to have a mix of both synced and regular profiles in their config file:

Specifying an alternative YAML file.

Granted allows you to specify an alternative YAML file for your Profile Registry's configuration. Should you wish to specify a different YAML file, run:

granted registry add <your-repo-url>/<filname.yml>

Specifying only a subfolder

If you have subfolder such as:

├── team_dev
│ ├── config1
│ ├── config2
│ ├── granted.yml

├── team_ops
│ ├── config3
│ ├── config4
│ ├── custom.yml

Then you can specify only the subfolder containing a granted.yml file:

granted registry add <your-repo-url.git>/<sub-folder>/

Or with custom file name as:

granted registry add <your-repo-url.git>/<sub-folder>/<filename.yml>

Syncing a Profile Registry

Adding a Profile Registry is sufficient to sync the granted.yml config file. Once per day Granted will automatically sync the repositories contained within your Profile Registry. By default, his process will be invoked when you run granted credential-process or asssume commands.

Should you wish to invoke a manual sync, run:

granted registry sync

This will loop over the repositories associated with your Profile Registry and will pull the latest changes from the remote origin, performing a sync operation.


When using AWS CLI with granted credential-process you will not be notified of failed Profile Registry syncs. This occurs as AWS expects specific JSON STDOUT when configured with sourcing credentials with an external process. In that case, you can run assume or granted registry sync to view the issue. Add verbose flag like assume --verbose to view the debug logs.

Removing a Profile Registry

To unsubscribe a repository from Granted's Profile Registry run the following command:

granted registry remove

This will display all repositories subscribed to Granted's Profile Registry and will prompt you to choose a repository to unsubscribe.