Server Secrets

It is possible to provide a token or credentials for a number of external services. These may be used to lift a rate limit or provide access to private resources from a self-hosted instance.

There are two ways of setting secrets:

Via environment variables. This is a good way to set them in a PaaS environment.

DRONE_TOKEN=...
DRONE_ORIGINS="https://drone.example.com"

Via checked-in config/local.yml:

public:
  services:
    drone:
      authorizedOrigins: ['https://drone.example.com']
private:
  drone_token: '...'

For more complex scenarios, configuration files can cascade. See the node-config documentation for details.

Authorized origins

Several of the badges provided by Shields allow users to specify the target URL/server of the upstream instance to use via a query parameter in the badge URL (e.g. https://img.shields.io/nexus/s/com.google.guava/guava?server=https%3A%2F%2Foss.sonatype.org). This supports scenarios where your users may need badges from multiple upstream targets, for example if you have more than one Nexus server.

Accordingly, if you configure credentials for one of these services with your self-hosted Shields instance, you must also specifically authorize the hosts to which the credentials are allowed to be sent. If your self-hosted Shields instance then receives a badge request for a target that does not match any of the authorized origins, one of two things will happen:

if credentials are required for the targeted service, Shields will render an error badge.
if credentials are optional for the targeted service, Shields will attempt the request, but without sending any credentials.

When setting authorized origins through an environment variable, use a space to separate multiple origins. Note that failing to define authorized origins for a service will default to an empty list, i.e. no authorized origins.

It is highly recommended to use https origins with valid SSL, to avoid the possibility of exposing your credentials, for example through DNS-based attacks.

It is also recommended to use tokens for a service account having the fewest privileges needed for fetching the relevant status information.

Services

Azure DevOps

AZURE_DEVOPS_TOKEN (yml: private.azure_devops_token)

An Azure DevOps Token (PAT) is required for accessing private Azure DevOps projects.

Create a PAT using an account that has access to your target Azure DevOps projects. Your PAT only needs the following scopes:

Build (read)
Release (read)
Test Management (read)

Bitbucket (Cloud)

BITBUCKET_USER (yml: private.bitbucket_username)
BITBUCKET_PASS (yml: private.bitbucket_password)

Bitbucket badges use basic auth. Provide a username and password to give your self-hosted Shields installation access to private repositories hosted on bitbucket.org.

Bitbucket Server

BITBUCKET_SERVER_ORIGINS (yml: public.services.bitbucketServer.authorizedOrigins)
BITBUCKET_SERVER_USER (yml: private.bitbucket_server_username)
BITBUCKET_SERVER_PASS (yml: private.bitbucket_server_password)

Bitbucket badges use basic auth. Provide a username and password to give your self-hosted Shields installation access to a private Bitbucket Server instance.

CurseForge

CURSEFORGE_API_KEY (yml: private.curseforge_api_key)

A CurseForge API key is required to use the CurseForge API. To obtain an API key, signup to CurseForge Console with a Google account and create an organization, then go to the API keys page and copy the generated API key.

Discord

Using a token for Discord is optional but will allow higher API rates.

DISCORD_BOT_TOKEN (yml: private.discord_bot_token)

DockerHub

Using authentication for DockerHub is optional but can be used to allow higher API rates or access to private repos.

DOCKERHUB_USER (yml: private.dockerhub_username)
DOCKERHUB_PAT (yml: private.dockerhub_pat)

DOCKERHUB_PAT is a Personal Access Token. Generate a token in your account security settings with "Read-Only" or "Public Repo Read-Only", depending on your needs.

Drone

DRONE_ORIGINS (yml: public.services.drone.authorizedOrigins)
DRONE_TOKEN (yml: private.drone_token)

The self-hosted Drone API requires authentication. Log in to your Drone instance and obtain a token from the user profile page.

GitHub

GITHUB_URL (yml: public.services.github.baseUri)
GH_TOKEN (yml: private.gh_token)

Because of GitHub rate limits, you will need to provide a token, or else badges will stop working once you hit 60 requests per hour, the unauthenticated rate limit.

You can create a personal access token (PATs) through the GitHub website. When you create the token, you can choose to give read access to your repositories. If you do that, your self-hosted Shields installation will have access to your private repositories.

For most users we recommend using a classic PAT as opposed to a fine-grained PAT. It is possible to request a fairly large subset of the GitHub badge suite using a fine-grained PAT for authentication but there are also some badges that won't work. This is because some of our badges make use of GitHub's v4 GraphQL API and the GraphQL API only supports authentication with a classic PAT.

When a gh_token is specified, it is used in place of the Shields token rotation logic.

GITHUB_URL can be used to optionally send all the GitHub requests to a GitHub Enterprise server. This can be done in conjunction with setting a token, though it's not required.

GH_CLIENT_ID (yml: private.gh_client_id)
GH_CLIENT_SECRET (yml: private.gh_client_secret)

These settings are used by shields.io for GitHub OAuth app authorization but will not be necessary for most self-hosted installations. See production-hosting.md.

Gitea

GITEA_ORIGINS (yml: public.services.gitea.authorizedOrigins)
GITEA_TOKEN (yml: private.gitea_token)

A Gitea Personal Access Token is required for accessing private content. If you need a Gitea token for your self-hosted Shields server then we recommend limiting the scopes to the minimal set necessary for the badges you are using.

GitLab

GITLAB_ORIGINS (yml: public.services.gitlab.authorizedOrigins)
GITLAB_TOKEN (yml: private.gitlab_token)

A GitLab Personal Access Token is required for accessing private content. If you need a GitLab token for your self-hosted Shields server then we recommend limiting the scopes to the minimal set necessary for the badges you are using.

Jenkins CI

JENKINS_ORIGINS (yml: public.services.jenkins.authorizedOrigins)
JENKINS_USER (yml: private.jenkins_user)
JENKINS_PASS (yml: private.jenkins_pass)

Provide a username and password to give your self-hosted Shields installation access to a private Jenkins CI instance.

Jira

JIRA_ORIGINS (yml: public.services.jira.authorizedOrigins)
JIRA_USER (yml: private.jira_user)
JIRA_PASS (yml: private.jira_pass)

Provide a username and password to give your self-hosted Shields installation access to a private JIRA instance.

Libraries.io/Bower

LIBRARIESIO_TOKENS (yml: private.librariesio_tokens)

Note that the Bower badges utilize the Libraries.io API, so use this secret for both Libraries.io badges and/or Bower badges.

Just like the *_ORIGINS type secrets, this value can accept a single token as a string, or a group of tokens provided as an array of strings. For example:

private:
  librariesio_tokens: my-token
## Or
private:
  librariesio_tokens: [my-token some-other-token]

When using the environment variable with multiple tokens, be sure to use a space to separate the tokens, e.g. LIBRARIESIO_TOKENS="my-token some-other-token"

Nexus

NEXUS_ORIGINS (yml: public.services.nexus.authorizedOrigins)
NEXUS_USER (yml: private.nexus_user)
NEXUS_PASS (yml: private.nexus_pass)

Provide a username and password to give your self-hosted Shields installation access to your private nexus repositories.

npm

NPM_ORIGINS (yml: public.services.npm.authorizedOrigins)
NPM_TOKEN (yml: private.npm_token)

Generate an npm token to give your self-hosted Shields installation access to private npm packages

Open Build Service

OBS_USER (yml: private.obs_user)
OBS_PASS (yml: private.obs_user)

Only authenticated users are allowed to access the Open Build Service API. Authentication is done by sending a Basic HTTP Authorisation header. A user account for the reference instance is a SUSE IdP account, which can be created here.

While OBS supports API tokens, they can only be scoped to execute specific actions on a POST request. This means however, that an actual account is required to read the build status of a package.

OpenCollective

OPENCOLLECTIVE_TOKEN (yml: private.opencollective_token)

OpenCollective's GraphQL API only allows 10 reqs/minute for anonymous users. An API token can be provided to access a higher rate limit of 100 reqs/minute.

Pepy

PEPY_KEY (yml: private.pepy_key)

The Pepy API requires authentication. To obtain a key, Create an account, sign in and obtain generate a key on your account page.

PyPI

PYPI_URL (yml: public.pypi.baseUri)

PYPI_URL can be used to optionally send all the PyPI requests to a Self-hosted Pypi registry, users can also override this by query parameter pypiBaseUrl.

SymfonyInsight (formerly Sensiolabs)

SL_INSIGHT_USER_UUID (yml: private.sl_insight_userUuid)
SL_INSIGHT_API_TOKEN (yml: private.sl_insight_apiToken)

The SymfonyInsight API requires authentication. To obtain a token, Create an account, sign in and obtain a uuid and token from your account page.

SonarQube

SONAR_ORIGINS (yml: public.services.sonar.authorizedOrigins)
SONARQUBE_TOKEN (yml: private.sonarqube_token)

Generate a token to give your self-hosted Shields installation access to a private SonarQube instance or private project on a public instance.

StackApps (for StackExchange and StackOverflow)

STACKAPPS_API_KEY: (yml: private.stackapps_api_key)

Anonymous requests to the stackexchange API are limited to 300 calls per day. To increase your quota to 10,000 calls per day, create an account at StackApps and register an OAuth app. Having registered an OAuth app, you'll be granted a key which can be used to increase your request quota. It is not necessary to performa full OAuth Flow to gain an access token.

TeamCity

TEAMCITY_ORIGINS (yml: public.services.teamcity.authorizedOrigins)
TEAMCITY_USER (yml: private.teamcity_user)
TEAMCITY_PASS (yml: private.teamcity_pass)

Provide a username and password to give your self-hosted Shields installation access to your private nexus repositories.

Twitch

TWITCH_CLIENT_ID (yml: private.twitch_client_id)
TWITCH_CLIENT_SECRET (yml: private.twitch_client_secret)

Register an application in the Twitch developer console in order to obtain a client id and a client secret for making Twitch API calls.

Weblate

WEBLATE_ORIGINS (yml: public.services.weblate.authorizedOrigins)
WEBLATE_API_KEY (yml: private.weblate_api_key)

By default Weblate throttles unauthenticated request to only 100 requests per day, after this you will need an API key or else badges will stop working.

You can find your Weblate API key in your profile under "API access".

YouTube

YOUTUBE_API_KEY (yml: private.youtube_api_key)

The YouTube API requires authentication. To obtain an API key, log in to a Google account, go to the credentials page, and create an API key for the YouTube Data API v3.

Error reporting

SENTRY_DSN (yml: private.sentry_dsn)

A Sentry DSN may be used to send error reports from your installation to Sentry.io. For more info, see the self hosting docs.

Tutorial: server-secrets

server-secrets

Server Secrets

Authorized origins

Services

Azure DevOps

Bitbucket (Cloud)

Bitbucket Server

CurseForge

Discord

DockerHub

Drone

GitHub

Gitea

GitLab

Jenkins CI

Jira

Libraries.io/Bower

Nexus

npm

Open Build Service

OpenCollective

Pepy

PyPI

SymfonyInsight (formerly Sensiolabs)

SonarQube

StackApps (for StackExchange and StackOverflow)

TeamCity

Twitch

Weblate

YouTube

Error reporting