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 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 .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 to marc/myrepo/dev/api-server then a user who has admin rights on marc/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 to secrethub_export_<namespace>_<repo>_<timestamp>.zip with the timestamp formatted as YYYYMMDD_HHMMSS.