Connections
note
This information is only relevant for Admins managing a Playground Private Exchange.
Overview
Connections is the one place in the Control Panel where you manage everything your Playground connects to. Open it from Control Panel → Advanced → Connections.
Each connection is a card showing its logo, what it does and its current status. Choose Set up, Manage or Change to open its settings in a pop-up. The ? icon next to a card's title opens the guide for that connection.
| Group | Card | What it is |
|---|---|---|
| Source control | Bitbucket | Where the source code of your plays lives. See Setup Bitbucket below |
| Sign-in methods | Switch to allow sign-in with Google | |
| Salesforce | Switch to allow sign-in with Salesforce | |
| SAML 2.0 | Single sign-on with your identity provider. See SAML 2.0 | |
| OpenID Connect | Single sign-on with an OpenID Connect provider. See OpenID Connect | |
| Sign-in policy | Allow any method, or require single sign-on. See Sign-in Methods & Policy |
note
The SAML 2.0 and OpenID Connect cards, and the Sign-in policy card, appear once single sign-on is made available under Control Panel → General → Advanced Features.
Card status
| Status | Meaning |
|---|---|
| Connected / Enabled (green) | Saved and working, or turned on |
| Token expires in N days (amber) | The Bitbucket token has 14 days or less left. Create a new token and update it |
| Connected - add token expiry date (amber) | An older connection saved before the expiry date was required. Open it, enter the date and save |
| Configured, not enabled (amber) | Single sign-on details are saved, but sign-in is not turned on yet |
| Token expired (red) | The Bitbucket token has expired and Playground can no longer reach your repositories |
| Not set up / Not connected / Turned off (grey) | Nothing is configured, or the switch is off |
Source control
Playground can connect to a git based version control system to keep your code safe under your IP. This makes sure that you always have control over your code even if you are not planning to use Playground in future.
Currently, Playground supports Bitbucket. Only one source control connection is used at a time.
Setup Bitbucket
Bitbucket provides a flexible way to configure different workspaces for a different stream of work. Playground takes leverage of this concept of workspace & always encourages creating a dedicated workspace for it.
Below are the steps to create a workspace & enable it with Playground platform.
1. Create a New Workspace
In Bitbucket, open the workspace menu and choose Create workspace.
note
The workspace name is open & can be set to anything. We recommend Playground to make it obvious for other users.
Bitbucket creates a Workspace Id for it. You will see it in the address of the workspace, bitbucket.org/<workspace-id>/. This Workspace Id is one of the values used in the setup later (Workspace (alias)).
2. Create a New Project
For further segregation, Bitbucket has the concept of Projects. Since we are only connecting one Playground with Bitbucket, create a single project in the new workspace.
note
Once the project is created, Bitbucket opens the project page. Take these values from the address in your browser (bitbucket.org/<workspace-id>/workspace/projects/<KEY>):
Workspace Id, which is the Workspace (alias)Key, which is the Project key
3. Create a Scoped API Token
Bitbucket uses scoped API tokens, which replace app passwords. Create one from your Atlassian account: Account settings → Security → API tokens → Create API token with scopes. Choose Bitbucket as the app and give the token exactly these scopes:
| Scope | Name | What Playground uses it for |
|---|---|---|
read:user:bitbucket | User: Read | Identify the account the token belongs to |
read:project:bitbucket | Projects: Read | Find the project new repositories are created in |
read:repository:bitbucket | Repositories: Read | Read the source of your plays |
write:repository:bitbucket | Repositories: Write | Push new versions of your plays |
admin:repository:bitbucket | Repositories: Admin | Create the repository for a new play |
read:pullrequest:bitbucket | Pull requests: Read | Read pull request information for your repositories |
The same list, with a copy button for each scope, is shown in the Bitbucket pop-up under Connections.
Choose an expiry date. Tokens always expire, so you will create a new one and update it here before that date.
note
Atlassian shows the token only once. Copy it and note its expiry date: both are used in the next step.
4. Enter Details in Connections
Open Connections, select the Bitbucket card and choose Set up. Fill in the pop-up:
| Field | What to enter |
|---|---|
| Atlassian account email | The email of the Atlassian account that created the API token |
| Scoped API token | The token from step 3. It is stored encrypted and never shown again |
| Token expiry date (required) | The expiry date of the token. Playground shows how long is left on the card |
| Commit email | The email shown as the author of commits Playground makes |
| Commit author name | The name shown for all Playground activity in Bitbucket. Use Playground Admin to make it obvious |
| Project key | The project key gathered in step 2 |
| Workspace (alias) | The Workspace Id gathered in step 2 |
Hover the i icon next to any field for a short explanation. Choose Save.
note
Once saved, the token is used in the background and is never sent back to your browser. To replace it, enter a new token and its new expiry date. Leave the token field empty to keep the saved one.
All these details are stored securely in encrypted state in the database and gets decrypted only when needed. To know more about it, Visit our Security Overview page in this documentation
5. Test the Connection
Choose Test connection in the pop-up. Playground checks the saved credentials against your workspace and tells you what to fix:
| Result | What to do |
|---|---|
| Connected | Nothing. Repositories in the workspace are reachable |
| The provider rejected the username or token | Check the email and the token, or create a new token |
| The credentials work but lack permission | Add the missing scopes in step 3 |
| The workspace was not found | Check the Workspace (alias) value |
| The token expired | Create a new token and save it with its new expiry date |
You can also test by creating a play with the steps in this document, using https://lkat-playg@bitbucket.org/lkat-playg/pg-demo.git as the public git url. If a play is created successfully, your connection is complete & tested.
Renewing an expiring token
When the card turns amber, create a new scoped token with the same scopes (step 3), then open Manage, paste the new token, enter its new expiry date and Save. Use Test connection to confirm.
Sign-in methods
Google, Salesforce and single sign-on are managed from the same page. To enable single sign-on, require it for everyone, or set up break-glass accounts, read Sign-in Methods & Policy.