Managing a repository
Central to the SecretHub workflow are repositories.
A repository works like a secure central filesystem, allowing a select group of users to create directories and store and retrieve secrets. Under the hood everything inside a repository is encrypted per secret per account, so only the accounts that require access to a secret are able to decrypt it.
Permissions on repositories are defined by access rules on directories. To read more on access rules, see this page.
SecretHub repositories are always tied to a namespace. This can be a personal private namespace or a shared organization namespace. SecretHub users can be members of multiple repositories.
To manage a repository, the
repo subcommand can be used.
Below each command is described in detail.
repo init- create a new repository
repo inspect- inspect details of a repository
repo ls- list all repositories you have access to
repo rm- permanently remove a repository
repo invite- invite a user to join a repository
repo revoke- revoke an account from a repository
repo export- export a repository to a
To initialize a new repository, you can run the
repo init command:
secrethub repo init [options] <namespace>/<repo>
repo init command creates a new repository with you as the sole root administrator.
- The path to the repository to create. Note that you can only create repositories in your own private namespace or in an organization namespace you are a member of.
To print the details of a repository in JSON, you can use the
repo inspect command:
secrethub repo inspect [options] <namespace>/<repo>
- The path to the repository to inspect.
To list all repositories you have access to, you can use the
repo ls command:
secrethub repo ls [options]
repo ls command prints out a list of paths to repositories you have access to.
Keep an eye on the
STATUS field, as it indicates the security status of the contents of a repository.
For instance, repositories containing a flagged secret will have their status flagged.
For scripting, you may want to disable the table format output. Use the
--quietflag to make the command only print out path values.
- Only print path values.
To permanently remove a repository, you can use the
repo rm command:
secrethub repo rm [options] <namespace>/<repo>
This action cannot be undone, so proceed with caution here.
repo rm command permanently removes a repository and all the directories, secrets and service accounts it contains.
- The repository to permanently remove.
To invite another user to collaborate on a repository, you can use the
repo invite command:
secrethub repo invite [options] <namespace>/<repo> <username>
repo invite command adds the given user to the repository.
However, this does not yet give the user permission to read or write the repository’s contents.
To allow that, you must create an access rule for the user by running the
acl set command.
Read more about the
acl set command on this page.
- The path to the repository to invite the user to.
- The user to invite to the repository.
To revoke an account’s access to a repository, you can use the
repo revoke command.
secrethub repo revoke [options] <namespace>/<repo> <account-name>
repo revoke command does the following:
- Remove the account from the repository, destroying it if it concerns a service account.
- Flag all secret versions that have ever been exposed to the revoked account (e.g. the account has read, written secret values). A secret is considered flagged for rotation when the latest version of that secret is flagged.
- Print out a list of all secrets that have to be rotated.
After running the
repo revoke command, you will have to rotate each affected secret.
Until each flagged secret has been rotated, the
ls command will continue to indicate flagged secrets.
A secret is considered rotated when a new version has been written to that secret and is taken in use by services.
Depending on context, you may want to keep the old version or remove it with the
While some secrets require manual rotation, others can be programmatically (re)generated. Support for automatic rotation is coming soon.
Some restrictions apply to the
repo revoke command:
- User accounts can only be revoked by root administrators.
- Service accounts can be revoked by any user with
adminrights on all paths the service account has access to. For instance, if a service account has access to
marc/myrepo/dev/api-serverthen a user who has
marc/myrepo/devcan revoke the service.
- Every repo must always have at least one root administrator. In other words, it is impossible to revoke yourself if you are the last root administrator.
- The path to the repository to revoke the account from.
- The account name (username or service name) to revoke.
To export an entire repository to a
.zip file, you can use the
repo export command:
secrethub repo export [options] <namespace>/<repo> [<zip_file_name>]
This action exports all secrets to a
.zip file in plaintext, so proceed with caution here.
You are responsible for the protection of the secrets inside this
export command can be useful when you want to backup secrets or want to migrate to another technology.
Note that exporting secrets will log audit events, but will not change or remove the repository’s contents.
- The repository to export.
- The file name to assign to the exported
.zipfile. Defaults to
secrethub_export_<namespace>_<repo>_<timestamp>.zipwith the timestamp formatted as