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 within the Workspace section of Settings. For each asset, and depending on your needs, you are able to configure the level of access users in your workspace should have.
Workspace assets are managed in the following tabs:
- Data sources: Shared data connections
- Secrets: Shared secrets
- Integrations: Hex API, GitHub or GitLab repositories, and external file integrations.
A list of projects which have imported a given workspace asset is available by clicking the link in the Usage column.
Shared data connections
Shared data connections are available for workspaces on Professional, Teams, and Enterprise plans.
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 Secrets
Shared secrets are available for workspaces on Professional, Teams, and Enterprise plans.
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.
GitHub packages
GitHub packages are only available for workspaces on Teams and Enterprise plans.
First, an Admin must connect a GitHub account to Hex. To do so, navigate to the Integrations tab under the "Workspace" header 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.
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.
External file integrations
External file integrations are available for workspaces on Professional, Teams, 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 role | Project permission | Has access to the data connection | Effective project permission | Comment |
|---|---|---|---|---|
| Editor | Can Edit or Full Access | Yes | Can Edit or Full Access | |
| Editor | Can Edit or Full Access | No | Downgraded to Can View | Hex 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 |
| Admin | Can Edit or Full Access | Always | Can Edit or Full Access | Admins 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.