Create and use secrets

Use secrets to store credentials, passwords, access tokens, or other privileged information in an encrypted format. Include secrets in chains to securely pass sensitive data required for completing specific chain steps.

Guidelines for using secrets

When you run PulseUno chains, secrets provide a secure way of including private data, such as passwords and access tokens for third-party tools.

Example: To run a build job that requires restarting an external server, create secrets to store the server username and password, and then use the secrets in your build job. This keeps the credentials from being exposed.

You can create and store secrets in PulseUno or add a provider from which to retrieve secrets for your build jobs. PulseUno integrates with the HashiCorp Vault secrets manager.

Guidelines for creating and using secrets:

  • You can add secrets at the global, space, or product level. Global secrets are shared across all spaces and products in your PulseUno instance. Space and product secrets are scoped to a specific space or product.

  • Space secrets override global secrets that have the same names, and product secrets override both global and space secrets that have the same names.

  • To use HashiCorp Vault as the secrets provider, connect your HashiCorp Vault instance to a PulseUno space. PulseUno can read HashiCorp Vault secrets only if they are stored in the Key/Value (K/V) secrets engine, version 1 or 2.

    For details on how to set up the K/V secrets engine and write secrets to it, see the HashiCorp Vault documentation.

  • To add secrets providers, you need administrator or space owner permissions.

    To add secrets, you need the following permissions:

    Level Role permissions
    Global secrets Administrator
    Space secrets Space owner, administrator
    Product or Git repository secrets Product owner, administrator

    For details about assigning roles, see Manage members and teams.

  • PulseUno chains consume secrets through chain variables, where a secret is set as a variable value. For details, see Reference secrets in chains.

  • Secrets are displayed obscured in logs. If a secret is set as a private variable, the secret's name is also displayed obscured.

  • Secrets are stored in the database as AES 256 encrypted values.

    Caution: PulseUno uses a master.key file to encrypt all private data in the database. If the master.key file is lost, the private data can no longer be decrypted. You need to generate a new master.key and re-enter all secrets and credentials for secrets providers. For details, see Secure your PulseUno installation.

Back to top

Create and modify secrets

Create global secrets and use them across multiple spaces and products. To limit the scope, add secrets to a specific space, product, or Git repository.

To create or modify a secret:

  1. Select where you want to add a secret:

    Add a global secret Go to Administration > Secrets.
    Add a secret to a space On the top navigation bar, select a space from the spaces list. Then select Settings > Secrets on the sidebar.
    Add a secret to a product After selecting a space, open the relevant product or Git repository from the product list. Then select Settings > Secrets on the sidebar.

  2. On the toolbar, click New Secret .

  3. In the Create New Secret dialog box, provide the name and value of your secret:

    Field Description
    Name

    Enter a name for the secret. You can use Latin characters, numbers, and underscores. Names are not case-sensitive.

    Secrets defined at the same level must have unique names. But you can create secrets with the same names at different levels, for example, at the product and space levels.

    If secrets have the same names, lower-level secrets take precedence over those defined at a higher level. For example, product secrets override space and global secrets.
    Value Enter the secret's value.

  4. Click Save.

  5. To change a secret's value, select the secret in the list, and click Edit Secrets on the toolbar. For security purposes, PulseUno doesn't display the old value of the secret.

  6. To remove a secret, select the secret in the list, click Delete on the toolbar, and confirm.

Back to top

Add a HashiCorp Vault secrets provider

To access secrets stored in HashiCorp Vault, add a HashiCorp Vault secrets provider to a space. You can then use HashiCorp Vault secrets in chains across all products within the space.

To create a secrets provider:

  1. On the top navigation bar, select a space from the spaces list.

  2. On the sidebar, select Settings > Secret Providers.

  3. On the toolbar, click New Secret Provider .

  4. In the Create New Secret Provider dialog box, enter the details of your HashiCorp Vault instance:

    Field Description
    Name Enter a name for the secret provider.
    Vault URL

    Enter the URL and port of your HashiCorp Vault server, for example:

    https://127.0.0.1:8200/

    Role ID

    Enter the role ID for logging in to the HashiCorp Vault server.

    PulseUno uses the AppRole auth method to fetch the access token for HashiCorp Vault. To authenticate with HashiCorp Vault, the AppRole auth method requires the role ID and secret ID for the role assigned to PulseUno.

    For details on how to create a role and fetch the role ID and secret ID, see the HashiCorp Vault documentation.
    Secret ID Enter the secret ID for logging in to HashiCorp Vault.
    Role Path

    (Optional) Enter the path at which the AppRole is mounted.

    Leave empty to use the default mount path: approle
    Namespace HashiCorp Vault Enterprise only: (Optional) If you use namespaces, enter the mount path to the dedicated namespace from which to fetch secrets.

  5. Click Save.

Back to top

Reference secrets in chains

To include a secret in a chain, add a chain variable and specify the secret as the variable value. For details about adding variables to chains, see Define chain and global variables.

When referencing secrets in variables, use the following syntax:

Secret type Syntax
Secrets defined in PulseUno

{{secrets["<secretName>"]}}

where <secretName> is the name of the secret created in PulseUno.
HashiCorp Vault secrets

{{secrets["<secretProvider>:<secretPath>"]/<key>}}

where:

  • <secretProvider> is the name of the HashiCorp Vault secrets provider, as defined in PulseUno.

  • <secretPath> is the path to the secret in HashiCorp Vault. For example:

    secret/chains/credentials

    When using a K/V version 2 secrets engine, insert the data segment into the path. For example:

    secret/data/chains/credentials

    Tip: To check that the path is correct, run the HashiCorp Vault read command.

  • <key> is the key, or a JSON pointer to the key, whose value you want to access.

Suppose you have added a HashiCorp Vault secrets provider called credVault.

Your secret is located at the secret/data/library path in HashiCorp Vault and contains the following JSON data:

Copy code 
{
    "libraryName": "Wonderland Library",
    "location": "123 Library Street, Booktown",
    "foundingYear": 1990,
    "books": [
        {
            "title": "The Adventures of Alice",
            "author": {
                "name": "Lewis Carroll",
                "birthYear": 1832,
                "nationality": "British"
            },
            "genres": [
                "Fantasy",
                "Adventure"
            ],
            "publicationYear": 1865
        }
    ],
    "staff": [
        {
            "name": "Emily Librarian",
            "position": "Head Librarian",
            "yearsOfService": 12
        },
        {
            "name": "Sam Assistant",
            "position": "Library Assistant",
            "yearsOfService": 4
        }
    ]
}

Suppose that the secret value you need to fetch from the JSON data is Head Librarian on line 23.

In this case, use the following syntax to reference the secret value in a variable:

{{secrets["credVault:secret/data/library"]/staff/0/position}}

where staff/0/position is the JSON pointer:

staff Points to the property containing the array with the secret value.
0 Indicates that the secret value is located in the first object inside the array.
position Specifies the key whose secret value you want to fetch.

Back to top

See also: