Registry Extension

Updated 2 years ago by Admin

You can use registry extensions to provide your pipelines with docker login credentials. If your pipeline depends on private images, these credentials are used to authenticate with a remote registry and pull private images.


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

    Provides the endpoint used to make http requests to a registry extension.
    Provides the token used to authenticate http requests to the extension. This token is shared between the server and extension.

How it Works

The runner makes an HTTP POST request to retrieve a list of registry credentials. The runner matches the registry credentials with docker images in your yaml by comparing the registry address with the fully-qualified image url.


The registry extension receives an HTTP request to return a list of registry credentials. The JSON-encoded request body includes the repository and build information.

Request Body definition:

1 class Request {
2     repo: Repository;
3     build: Build;
4 }

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 registry extension should respond to the request with a 200 response code and a list of registry credentials in JSON format.

Registry definition:

1 class Registry {
2 address: string
3 username: string
4 password: string
5 }

Example response:

"address": "",
"username": "octocat",
"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 registry extension we recommend using our starter project as a base to jumpstart development.

How did we do?