Secret Extension

Updated 2 years ago by Admin

You can use secret extensions to provide your pipeline with secrets from a custom, third party source. For example, we created a reference secret extension to source secrets from Vault.

Here are some reference extensions:


You can register a secret extension with your runners by providing the following configuration parameters:

    Provides the endpoint used to make http requests to a secret extension.
    Provides the token used to authenticate http requests to the extension. This token is shared between the server and extension.
Secret extensions are registered with runners as opposed to the central server. This design is intentional. For example, runners in different regions or data centers may have access to different secrets.

How it Works

You can define an external secret resource in your Yaml configuration file. When you define an external secret, the runner makes an HTTP POST request to the secret extension to retrieve the external secret.

Example Yaml with external secret:

 1  kind: secret
2 name: username
3 get:
4 path: secrets/data/docker
5 name: username
7 ---
8 kind: secret
9 name: password
10 get:
11 path: secrets/data/docker
12 name: password


The secret extensions receives an HTTP request to return a named secret. The JSON-encoded request body includes the name of the secret being requested, as well as the repository and build information.

Request Body definition:

1  class Request {
2 name: string;
3 path: string;
4 repo: Repository;
5 build: Build;
6 }

1  class Repository {
2 id: int64;
3 uid: int64;
4 user_id: int64;
5 namespace: string;
6 name: string;
7 slug: string;
8 scm: string;
9 git_http_url: string;
10 git_ssh_url: string;
11 link: string;
12 default_branch: string;
13 private: boolean;
14 visibility: string;
15 active: boolean;
16 config: string;
17 trusted: boolean;
18 protected: boolean;
19 ignore_forks: boolean;
20 ignore_pulls: boolean;
21 cancel_pulls: boolean;
22 timeout: int64;
23 counter: int64;
24 synced: int64;
25 created: int64;
26 updated: int64;
27 version: int64;
28 }

1 class Build {
2 id: int64;
3 repo_id: int64;
4 number: int64;
5 parent: int64;
6 status: string;
7 error: string
8 event: string;
9 action: string;
10 link: string;
11 timestamp: int64;
12 title: string;
13 message: string;
14 before: string;
15 after: string;
16 ref: string;
17 source_repo: string;
18 source: string;
19 target: string;
20 author_login: string;
21 author_name: string;
22 author_email: string;
23 author_avatar: string;
24 sender: string;
25 params: [string][string];
26 cron: string;
27 deploy_to: string;
28 deploy_id: int64;
29 started: int64;
30 finished: int64;
31 created: int64;
32 updated: int64;
33 version: int64;
34 }


The secret extension should respond to the request with a 200 response code, and the secret encoded in JSON format. If access to the requested secret cannot be granted, the extension should return a 204 status code.

Response definition:

1 class Secret {
2 name: string
3 data: string
4 }

Example response:

{ "password": "correct-horse-battery-staple" }


The http request is signed per the http signatures draft specification use the shared secret. The receiver should use the signature to verify the authenticity and integrity of the webhook.

Starter Project

If you are interested in creating a secret extension we recommend using our starter project as a base to jumpstart development.

How did we do?