Skip to main content

Workspace assets

Assets such as Data connections and Secrets can be shared broadly with subsets of your team or with the entire workspace.

As an Admin, you can set up and configure shared workspace assets in the Workspace assets tab of the Settings panel. For each asset, and depending on your needs, you are able to configure the level of access users in your workspace should have.

Shared data connections#

Admins can create shared data connections that can be used by all users in their workspace. The process to create connections is the same as detailed in Data connections.


If you delete a shared connection it will be deleted from all projects that use it. Deletion cannot be undone.

Shared connections are found in the workspace assets section of the Admininstration page.

Shared Secrets#

Admins can create shared Secrets that can be used across all projects in the Workspace. If a shared Secret is imported into a project, the Secret value will be visible to any user authorized user who has Editor access to the project.

Shared secrets are found in the workspace assets section of the Admininstration page.

GitHub packages#

First, an Admin must connect a GitHub account to Hex. To do so, navigate to the Workspace assets tab and click the Connect button under the GitHub packages section. There may be additional set up steps to complete once a GitHub Admin approves the connection request if the Hex Admin is not also an Admin of the target GitHub organization.

In the GitHub authentication dialog, you can choose individual repositories that you want to connect to Hex or connect all repositories. After successful setup and authentication, you will be sent back to the Hex Settings panel.


If you need to disconnect the GitHub account on the Hex Admin page, you will also need to revoke access to the account in GitHub.

Install Packages#

Once you've authenticated a GitHub account, you can select individual packages to install to your Workspace by clicking the + Package button.

Add a package from a connected GitHub repository and configure the import parameters.

You can install a specific branch, tag, or commit of a package. If you install a branch (e.g. main), by default all projects will have access to the latest version of that branch. If you would prefer to pin the version of the package which is imported to Hex you should select either the tag or commit SHA of the desired version.

Package install instructions can be customized via the Install commands section of the Add a package dialog. If no optional commands are provided, by default the GitHub package is zipped and downloaded in its entirety.

If your GitHub package includes pip installable modules, you can specify how those packages are installed via a command similar to pip install ./. The details of your repository structure and content will dictate the specific install commands required.

Once you have successfully added a repository and package to Hex, it will be available to all workspace users. See Using packages for instructions on using GitHub packages in a project.

Understand shared asset permissions#

As an Admin, you can set who is able to use a workspace asset (which includes Data connections, Secrets, and GitHub packages). By default, a workspace asset is shared with all workspace users. This means users with either Author or Admin roles can use an asset in projects and Members will be able to view them. However, Guests of your workspace will not be able to use or view workspace assets by default, even when they are given Editor permissions on a project.


Workspace asset permissions do not control who can view the results derived from shared workspace assets (e.g. the output from querying a workspace data connection). Access to view a project is defined by its sharing permissions.

To set the permissions on a workspace asset, head to the Workspace assets tab of the Settings panel. You can either add a new asset or edit an existing one via the three-dot menu icon. Then, at the bottom of the modal, add the desired groups under the "Groups with access" heading.

Hex provides you with three built-in groups to add to an asset, whose membership is determined via a user's role within your workspace. You can learn more about workspace roles here.

  • Workspace (default): All Members, Authors, and Admins.
  • Workspace guests: Only Guests of a workspace.
  • Public: All users of a workspace, including users who are viewing an app shared with the web (and are not part of the workspace).

In addition to these groups, you can share a connection with any custom defined groups. You can learn more about defining groups here.


Getting started with workspace connections? We recommend using the default permissions, share with workspace, so that all workspace users have access to the shared connection.

If a user does not have access to a workspace asset, they are not able to edit projects which use that asset, effectively downgrading their project permissions to "Viewer". Here are some common scenarios that outline how workspace roles, project permissions, and data connection access may limit a user's access to a project.

Workspace roleProject permissionHas access to the data connectionEffective project permissionComment
AuthorEditor or OwnerYesEditor or Owner
AuthorEditor or OwnerNoDowngraded to ViewerHex will try to prevent you from adding a user as an Editor who does not have access to a workspace asset that is used in the project
AdminEditor or OwnerAlwaysEditor or OwnerAdmins inherit access to all workspace assets

Shared data connection permissions in practice#

Here are a few common examples to help you wrap your head around the best way to set up your permissions.

  • A data connection used for analytics: By default, a workspace data connection is shared with all users. This means that anyone with Editor permissions on a project can use this connection when editing Hex projects. Guests of your workspace will be prevented from using this connection as a project Editor.

  • A sensitive data connection: Consider sharing this data connection with a workspace-defined group, for example "Data Team".

    • When a user of the "Data Team" group creates a project, they will be able to add the connection to their project
    • Anyone outside of that group will not be able to add the data connection to their Hex projects (or see it as an option to be added).
    • If a member of "Data Team" tries to add a user outside of the "Data Team" as an Editor on a project they will not be able to, and will recieve a warning to this effect.
    • All Admins can be added as a project Editor to any project — because Admins can change permissions on a workspace asset to include themselves, they effectively already have this permission.
  • A data connection for interviewing candidates: If you're using Hex to run technical assessments for candidates (a great use case!), it's likely that you'll add the candidate as a Guest in your workspace. To allow a Guest to use a data connection, you'll need to explicitly add the "Workspace guests" group to the data connection.