Secrets are pieces of sensitive information stored securely by Atomist. Secrets are used by Rug Functions to provide access to secured systems, such as the GitHub API.

Handlers that invoke Rug Functions that require secrets must use the @Secrets decorator to declare to the Rug runtime that those secrets will be required during the execution of the handler’s CommandPlan:

class CloseIssueCommand implements HandleCommand {

The @Secrets decorator takes a comma separate list of secret paths. The decorator provides enough context to the Atomist Bot such that it can initiate the secure collection of the require secret data, such as a GitHub token collected via OAuth flow.


All sensitive data stored by Atomist are encrypted at rest in Vault.

There are currently two types of secrets:

  • GitHub tokens: automatically collected by the Atomist Bot
    • "github://user_token?scopes=repo" - repo scoped user token
    • "github://team_token?scopes=repo" - repo scoped team token Both user and team GitHub tokens require the scopes needed by the token to be provided as a comma-separated list.
  • Generic Secrets: manual collection
    • "secret://user?path=/some/secret" - generic user secret
    • "secret://team?path=/some/secret" - generic team secret

Generic Secrets

These are currently only available for very specific and mostly internal use cases as we currently have no secure public mechanism for collecting and storing them, though this is something we are hoping to support in the near future. They are mentioned here to avoid any confusion when seen in publically visible Handlers.