Secrets Management

At no point the external secrets are stored in GoCD, these secrets are looked up only when required, e.g if a job is configured to use external secrets, these secrets are looked up just before the job is assigned to an agent and transmitted securely to the agent.

To look up for secrets from an external Secrets Manager you would need to install a Secrets Plugin which supports a Secret Manager of your choice. A list of available Secrets Plugins can be found here.

GoCD comes bundled with a Secrets Plugin which encrypts and stores secrets on a file. For more information about the File based Secrets Plugin please refer to the .

A Secret Manager should be configured to lookup for secrets. A Secret Manager can be configured using the Secret Configuration, this configuration is specific to a plugin and would differ based on the plugin used.

Steps to configure a Secrets Manager, the below example uses the bundled File based Secrets Plugin,

Login into your GoCD server.
Go to Admin menu → Secret Management.
Click on button.
Enter a unique id for secret configuration. This id will be referred in GoCD configurations while using the secrets.
In the Plugin dropdown select the plugin which supports a Secret Manager of your choice. Once a plugin is selected an appropriate configuration is displayed below.

Users can define two types of rules
- Allow - Explicitly allows usage of the Secret Manager to a GoCD entity.
- Deny - Explicitly denies usage of the Secret Manager to a GoCD entity.
```
<deny type="environment" action="refer">resource_identifier</allow>
```

The rules have the following attributes,

By default if no rule is defined, none of the GoCD entities will have access to the Secret Manager. Hence the Secret Manager would be unusable.

Once a Secret Manager is configured, you will have to define a Secret Param to lookup for a secret from an external Secrets Manager.

The syntax of a Secret Param is: {{SECRET:[secret_config_id][secret_key]}} where,

secret_config_id: is the unique id provided while creating secret configuration.
secret_key: is the key which refers to a secret value stored in your external Secrets Manager.

Add a Secret Param

Currently, GoCD allows Secret Params to be added in the following places,

Password field for an SCM Material
Value field of an environment variable.

Secret Params defined anywhere else other than the above would be ignored and treated as a string.

Secrets from an external Secrets Manager are never stored in GoCD, hence the Secret Params are resolved just before they are required.

Secret Params defined as a password in a SCM Material are resolved just before a Material is picked up for an update.
Secret Params defined as an environment variable is resolved before assigning work to an agent.

If a Secret Param resolution fails the corresponding task would fail as well. This can lead to a failed job or a failed material update.

Wildcards (*) in type:

Using a wildcard (*) for type implies a given rule applies to all entity types. In this case, the supported entities are pipeline_group and environment.
```
<rules>
  <allow type="*" action="refer">production</allow>
</rules>
```
Note: type can have a wildcard(*) but it will not support pattern matching e.g. pipe*.
Wildcards (*) in action:

Using a wildcard (*) for action implies a given rule applies to any action on the Secret Config. Currently refer is the only supported action.

Note: action can have a wildcard(*) but it will not support pattern matching e.g. ref*.

Wildcards (*) in resource:

Resource name supports the wildcard characters ‘?’ and ‘*’ to represent a single or multiple (zero or more) wildcard characters.

Wildcard Matcher	Resource names
`group`	Matches `my_group` and `someother_group`, but not `testgroup` or `group1`.
`Production`	Matches and `Production_Team_B` but not `Team_ABC_Production_D`.
`group`	Matches `group`, `my_group` and `group_A`, but not `groABCup`.
`Team?_group`	Matches `Team_A_group`, `Team_B_group` but not `Team_ABC_group` or `Team__group`.

When multiple rules are defined, rules will be applied from top to bottom.

<rules>
    <allow action="refer" type="pipeline_group">my_group</allow>
</rules>