Skip to content

Push to server

With this feature you can connect a server and push the generated JSON directly to it. At the moment the plugin supports JSONBin, GitHub (direct commit or pull request), GitLab (direct commit or merge request) and custom servers.

The list of supported serversThe list of supported servers

If you connected multiple servers, the plugin will try to push the tokens to all of them one by one. The server list shows where each one pushes to, e.g. acme/tokens · main; click a server to change its settings.

Every field in a server form has a visible label. The ⓘ next to a label explains the field when you hover or focus it. Tokens and keys are masked; the eye in the field shows them. Optional fields such as the commit message are under More options. If you go back with unsaved changes, the form asks whether to save or discard them, and Remove at the bottom deletes the server’s settings and token from the profile after a confirmation.

For GitHub, GitHub PR, GitLab and GitLab MR, Test connection checks the token, the repository and the branch with read-only requests, so you find a typo before the first push. A problem is shown at the field it belongs to. Otherwise, Push to server reports the result of each server in a toast.

A connected JSONBin server and the Push to server buttonA connected JSONBin server and the Push to server button
  1. Open JSONBin and create an account.
  2. Copy your Master key from the API keys page into the Master key field. The plugin sends it as X-Master-Key, so an access key doesn’t work here.
  3. Add a name for the bin.
  4. Leave Bin ID empty to create a new bin on the first push. The plugin saves the new bin’s ID, so later pushes update the same bin. To use an existing bin, paste its ID.
JSONBin credentialsJSONBin credentials
  1. Create a fine-grained personal access token with Contents: Read and write for the repository (a classic token with repo scope works too). The Create token ↗ link in the form opens that page.
  2. Repository: owner/repository, or paste the repository URL from your browser. A URL that points at a branch (…/tree/develop) fills in the branch too.
  3. Branch: it must already exist.
  4. File path: the path of the file in the repository, e.g. tokens/design.tokens.json. If the file doesn’t exist, it will be created. If the file exists, it will be overwritten.
  5. Personal access token: paste the token.
  6. Under More options you can set a commit message. It defaults to Update tokens.

Splitting into several files. If Split collections into separate files or Split modes into separate files is enabled in the advanced settings, the file path field is labelled Folder and every file is written into it in a single commit — e.g. tokens → tokens/Colors.tokens.json, or tokens/Colors/Light.tokens.json when splitting by mode. The ⓘ shows an example path. To leave some collections out of the push, see Collections to push.

GitHub credentialsGitHub credentials

Instead of committing to a branch directly, the plugin commits the tokens to a separate branch and opens a pull request. Repository, file path and token work the same as for the GitHub server; the token also needs Pull requests: Read and write. The other fields:

  • Base branch (required). The branch the pull request targets, e.g. main.
  • Pull request branch (optional, under More options). The branch the tokens are committed to. Defaults to tokens-bruecke/update-tokens. It is reset to a new commit on top of the base branch on every push, so don’t commit anything else to it. The form doesn’t accept the base branch here.
  • Pull request title (optional). Defaults to chore(tokens): update tokens.
  • Pull request description (optional). If you leave it empty, the plugin won’t add a body to the PR.

If a pull request from that branch is already open, the plugin updates it instead of opening a new one. After a push, the toast shows an Open Pull Request link.

GitHub PR credentialsGitHub PR credentials
  1. You need a project access token with api scope. To push to a protected branch such as main, the token needs the Maintainer role; otherwise use the GitLab MR server, which opens a merge request instead. Once the project is filled in, the Create token ↗ link opens the project’s token settings.
  2. Project: paste the project URL from your browser, e.g. https://gitlab.acme.com/acme/frontend/design-system for a self-managed GitLab, or write group/project for gitlab.com. Subgroups and the SSH clone URL work too, and a URL that points at a branch (…/-/tree/develop) fills in the branch. The ⓘ next to the label shows how the plugin read host and project.
  3. Branch: it must already exist.
  4. File path: the path of the file in the repository, e.g. tokens/design.tokens.json. If the file doesn’t exist, it will be created. If the file exists, it will be overwritten.
  5. Project access token: paste the token.
  6. Under More options you can set a commit message. It defaults to Update tokens.

Splitting into several files. If Split collections into separate files or Split modes into separate files is enabled in the advanced settings, the file path field is labelled Folder and every file is written into it in a single commit — e.g. tokens → tokens/Colors.tokens.json, or tokens/Colors/Light.tokens.json when splitting by mode. The ⓘ shows an example path. To leave some collections out of the push, see Collections to push.

GitLab credentialsGitLab credentials

Instead of committing to a branch directly, the plugin commits the tokens to a separate branch and opens a merge request. Use it when the target branch is protected or changes should be reviewed. Project and file path work the same as for the GitLab server. The other fields:

  • Target branch (required). The branch the merge request targets, e.g. main. It must already exist; it can stay protected.
  • Project access token (required). A token with api scope and at least the Developer role, which may push to the merge request branch and open merge requests.
  • Merge request branch (optional, under More options). The branch the tokens are committed to. Defaults to tokens-bruecke/update-tokens. It is created on the first push and reset to a new commit on top of the target branch on every push, so don’t commit anything else to it, and don’t protect it. The form doesn’t accept the target branch here.
  • Commit message (optional). Defaults to Update tokens.
  • Merge request title (optional). Defaults to chore(tokens): update tokens.
  • Merge request description (optional). If you leave it empty, the merge request has no description.

If a merge request from that branch into the target branch is already open, the plugin updates it instead of opening a new one. After a push, the toast shows an Open Merge Request link.

GitLab MR credentialsGitLab MR credentials

While the tokens are split into separate files and a GitHub, GitHub PR, GitLab or GitLab MR server is set up, a Collections row appears under the servers when the file has more than one collection. It lists the collections that are pushed; click it to check or uncheck them. All collections are checked by default, and a collection added to the file later is checked too.

The Collections row under the servers, and a button that pushes 2 of 3 collectionsThe Collections row under the servers, and a button that pushes 2 of 3 collections

These servers only commit the files of the checked collections. The files of unchecked collections are not deleted: they stay in the repository as they are. This keeps a commit, pull request or merge request to the collections you changed. When some collections are unchecked, the push button says how many are pushed, e.g. Push 2 of 3 collections.

The Collections to push page with Spacing uncheckedThe Collections to push page with Spacing unchecked

The selection is saved in the profile. Download JSON, JSONBin, custom servers and the CLI always include every collection. With Omit collection names on, the output has no collection groups, so the row is hidden and every file is pushed.

There is a possibility to connect a custom server. In order to do that you need to specify an Endpoint URL starting with https:// (or http://), a Method (POST or PUT, by default it’s POST) and optional Headers, written as a JSON object, e.g. {"Authorization": "Bearer <token>"}. The form checks the URL and the headers when you leave the field.

JSONBin and custom servers always receive the whole JSON in one request: the split into separate files settings only apply to downloads, the CLI and the Git servers.

Custom server settingsCustom server settings