Skip to main content

Workspace assets

Share data connections and secrets with your workspace or specific user groups.

Admins can create and configure shared workspace assets from **Settings > Workspace **. Each asset can be shared with your entire workspace, or with specific user groups, according to your needs.

Workspace assets are managed in the following Settings tabs:

  • Data sources: Shared data connections
  • Secrets: Shared secrets
  • Integrations: Hex API, Git provider repositories, and cloud storage integrations like S3.

A list of projects which have imported a given workspace asset is available by clicking the link in the Usage column.

Shared data connections

  • Available on the Professional, Team, and Enterprise plans.
  • Users will need the Admin workspace role to create and share workspace data connections.
  • Users will need Can Edit or Full Access project permissions to use data connections shared with them.

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.

Admins can chose a default data connection to be used as the default data source in SQL cells. To assign a default data connection, select the three-dot menu to the right of a data connection, and select Set as default.


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

Shared Secrets

  • Available on the Professional, Team, and Enterprise plans.
  • Users will need the Admin workspace role to create and share workspace secrets.
  • Users will need Can Edit or Full Access project permissions to use secrets shared with them.

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 Can Edit or greater access to the project.

Git Package Import

Connect to a Git provider to access privately-hosted Git packages. Once a package is configured for a workspace, Editors can install the package in their projects.

  • Available on the Team and Enterprise plans.
  • Users must be an Admin to connect and configure Git packages.
  • Users need Can Edit permisson on a project to import a Git package.

Packages made available via Git Package Import need to be installed and imported into each project they are used in, which can increase kernel startup time. If you have packages that should be available for all Editors, or can take a while to install, consider using custom images instead.

Supported Git providers

The following Git providers are supported:

Git ProviderNotes
GitHubRepositories must be hosted on
GitHub Enterprise ServerAvailable to Hex workspaces on the Enterprise plan
GitLabRepositories must be hosted on
BitbucketRepositories must be hosted on

Set up a Git provider

Only Hex Admins are able to set up Git export repositories. The repository access must also be approved by a repository admin on the Git side.

  1. Head to the SettingsIntegrationsGit package import.
  2. Select + Git Provider, and select GitHub.
  3. Complete the app installation and OAuth flow on GitHub's side. You will be redirected back to Hex when completed.

Note that only one GitHub account can be connected to a given Hex workspace. Similarly, a given GitHub account can only be connected to one Hex workspace.

Configure Packages

Once you've configured a Git provider, you can select individual repos to be made available as packages. Once a package is configured for a workspace, Editors can import the package to their projects.

To configure a package, select the + Package button.

You can set up a package to install a specific branch, tag, or commit of a package. If you install a branch (e.g. main), when the package is imported, code from that branch will be made available. 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 Git 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.

You can also configure which groups can import the package into a project.

Once you have successfully added a repository and package to Hex, Editors will be able to import it to their projects for use. See Using packages for instructions on using Git packages in a project.

External file integrations

  • Available on the Professional, Team, and Enterprise plans.

Admins can create workspace-level access to external storage services. To do so, navigate to the Integrations tab under the "Workspace" header and click the Connect button under the "External file integrations" section. From here, a storage service can be selected. Once the connection is created, users with access can import the available files into their project.

Amazon S3

In order to connect to S3, you will need to input the name of the bucket, the region, and access keys for an IAM user. The IAM user must be allowed to perform the ListBucket and GetObject actions on the bucket and files and folders in the bucket.

The Enable writeback toggle will control whether or not this integration can export files from Hex to the S3 bucket. The IAM user will also need to have PutObject permissions in order to update files or create new files in the bucket.

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 Editor or Admin roles can use an asset in projects and Viewers 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 Can Edit 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 Settings, then Data sources to set permissions for shared data connections, Secrets for shared secrets, or Integrations for Github or Gitlab repositories. 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 Viewers, Editors, 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 Can View. 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
EditorCan Edit or Full AccessYesCan Edit or Full Access
EditorCan Edit or Full AccessNoDowngraded to Can ViewHex will try to prevent you from adding a user with "Can Edit" permissions who does not have access to a workspace asset that is used in the project
AdminCan Edit or Full AccessAlwaysCan Edit or Full AccessAdmins 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 Can Edit permissions on a project can use this connection when editing Hex projects. Guests of your workspace will be prevented from using this connection when then have Can Edit project permisisons.

  • 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" with Can Edit permissions on a project they will not be able to, and will receive a warning to this effect.
    • All Admins can be granted Can Edit permissions 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.