Manage Repositories
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.
All Commands
To manage repositories, you can use the following commands:
repo init
- create a new repositoryrepo inspect
- inspect details of a repositoryrepo ls
- list all repositories you have access torepo rm
- permanently remove a repositoryrepo invite
- invite a user to join a repositoryrepo revoke
- revoke an account from a repositoryrepo export
- export a repository to a.zip
file
Init
To initialize a new repository, you can run the repo init
command:
secrethub repo init [options] <namespace>/<repo>
The repo init
command creates a new repository with you as the administrator.
Arguments
-
<namespace>/<repo>
(string) - 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.
Inspect
To print the details of a repository in JSON, you can use the repo inspect
command:
secrethub repo inspect [options] <namespace>/<repo>
Arguments
-
<namespace>/<repo>
(string) - The path to the repository to inspect.
List
To list all repositories you have access to, you can use the repo ls
command:
secrethub repo ls [options] [<namespace>]
The 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
--quiet
flag to make the command only print out path values.
Arguments
-
<namespace>
(string) - When supplied, results are limited to repositories in this namespace.
Flags
-
-q, --quiet
(boolean) - Only print path values.
Remove
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.
The repo rm
command permanently removes a repository and all the directories, secrets and service accounts it contains.
Arguments
-
<namespace>/<repo>
(string) - The repository to permanently remove.
Invite
To invite another user to collaborate on a repository, you can use the repo invite
command:
secrethub repo invite [options] <namespace>/<repo> <username>
The 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.
Arguments
-
<namespace>/<repo>
(string) - The path to the repository to invite the user to.
-
<username>
(string) - The user to invite to the repository.
Revoke
To revoke an account’s access to a repository, you can use the repo revoke
command.
secrethub repo revoke [options] <namespace>/<repo> <account-name>
The 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 rm
command.
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
admin
rights on all paths the service account has access to. For instance, if a service account has access tomarc/myrepo/dev/api-server
then a user who hasadmin
rights onmarc/myrepo/dev
can 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.
Arguments
-
<namespace>/<repo>
(string) - The path to the repository to revoke the account from.
-
<account-name>
(string) - The account name (username or service name) to revoke.
Export
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>]
The 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.
Arguments
-
<namespace>/<repo>
(string) - The repository to export.
-
<zip_file_name>
(string) - The file name to assign to the exported
.zip
file. Defaults tosecrethub_export_<namespace>_<repo>_<timestamp>.zip
with the timestamp formatted asYYYYMMDD_HHMMSS
.