Cloning, pushing or pulling a private repository now asks you to pick one of your own Syntasa credentials instead of taking a pasted token. Here is which credential to choose, how to set one up, and what changed underneath.
The short answer
Pick a credential you created in Resources → Credentials that holds your personal access token — or, for an SSH remote, your SSH private key.
It is not a Syntasa config, not a data-store connection, and not your workspace's service account. It is an ordinary Syntasa credential object, created by you, whose value is a git token you generated on GitHub, GitLab, Bitbucket or Azure DevOps.
The dropdown lists only credentials your own login can read, so if it is empty, you have not created one yet — that is the first step below.
Why the dialog appeared
The shared workspace key is gone
Every workspace used to hold one SSH key at config/id_rsa that was downloaded into every pod. Every member could read it, and every push from every person arrived on the provider as the same identity — nobody could be told apart, and revoking one person's access meant rotating everyone's.
That key is deleted. Git operations now authenticate as the individual Syntasa user who ran them, using a credential that user chose. The prompt is the platform asking which one.
The old fallback — jupyterlab-git's own username/password box — is also gone. It invited pasting a raw token into a pod every workspace member can read, next to a "save my login temporarily" checkbox that left it retrievable there for an hour.
Before you clone
Create the credential
Go to Resources → Credentials and create a credential holding the right kind of secret for the remote you are cloning. The two transports need genuinely different things, and one cannot substitute for the other.
| https:// remote | ssh:// or git@host: remote |
|---|---|
Store a personal access token from your git provider. Give the key a name you will recognize — Grant it the scopes the work needs: read for cloning and pulling, write if you intend to push. | Store your SSH private key, the whole PEM block including the The key is loaded into a short-lived agent for the one operation and never written to the workspace. |
Do not cross the wires
A personal access token cannot authenticate an SSH remote, and a private key cannot authenticate an HTTPS one. Binding the wrong kind fails later at a push with Permission denied (publickey), which says nothing about the real cause. Match the credential to the URL scheme.
The flow
Clone a private repository
Open the Git sidebar and choose "Clone a Repository"
Paste the repository URL exactly as the provider's Clone button gives it — a
username@prefix is fine and is actually used as a hint later.Leave "Include submodules" unticked unless you need it
It now defaults to off and actually works. A recursive clone is slower, pulls repositories you did not name, and fails outright when a submodule lives on a host your credential is not authorized for.
Answer the "Git credential" dialog
It opens once git asks for authentication. The line at the top — Authenticating to … — is the URL the token is actually about to be sent to. Read it before you choose; it is the one thing worth checking every time.
Press "Use this credential"
The choice is verified against the remote before it is saved, so a wrong token or username fails here, in the dialog, rather than three days later on a push.
You will not be asked again for that repository
The choice is remembered per repository, per user, and survives a pod restart. Only that user is affected — your colleagues each make their own choice.
Field by field
What the dialog is asking for
| Credential | The Syntasa credential object holding your token or key. Only credentials your login can read are listed. If you have bound a repository on the same host before, that credential is pre-selected — never one from a different host. |
|---|---|
| Key | Which entry inside that credential holds the secret. It is hidden when the credential has exactly one key — there is nothing to ask. With several keys you pick from a list. Credentials backed by AWS Secrets Manager, GCP Secret Manager or Azure Key Vault report no keys at all, so the field becomes a text box and you type the entry's name. |
| Git username | The account name sent alongside the token. What belongs here depends entirely on your provider — see the table below. Hidden for SSH remotes, because SSH never sends a username. Leave it blank to use your Syntasa username. |
| Paste a token instead | A one-off escape hatch for HTTPS. The token is used for that operation and not saved anywhere. Useful for a quick read-only clone; not a substitute for a credential you will use repeatedly. Not offered for SSH. |
The field people get wrong
Git username, per provider
Providers disagree about what this means, and a correct token with the wrong account name fails identically to a bad token. This is the single most common support round trip.
| Provider | What to put in Git username |
|---|---|
| GitHub | Ignored when the secret is a personal access token. Anything works; leave the default. |
| GitLab | Any value is accepted when the secret is a personal access token. Leave the default. |
| Bitbucket | Checked, and it matters. Use x-token-auth for a repository, project or workspace access token. For an Atlassian API token, use x-bitbucket-api-token-auth or your exact Bitbucket username, case sensitive as shown on your account Settings page. Never your email address, for either kind. |
From a notebook cell
Bind a repository in code
If you would rather not go through the dialog — scripting a workspace setup, say — synutils.git writes the same binding. Available in both the Python and Scala kernels.
# Bind a repository to one of your credentials
synutils.git.setCredential(
"https://github.com/syntasa/syn-data", # the remote, as `git remote -v` shows it
"my-github-pat", # your Syntasa credential name
key="token", # optional if the credential has exactly one key
username="x-token-auth") # optional; defaults to your Syntasa username
# See what you have bound
synutils.git.getCredentials()
# Drop a binding — needed when a repository's remote URL changes
synutils.git.clearCredential("https://github.com/syntasa/syn-data")
One difference from the dialog
setCredential does not test the credential — no token is read or sent when you call it. The dialog validates before saving; this does not, so a typo surfaces on your first push. The dialog is the safer route when you are unsure.
Run it in the notebook where you are actually working. The binding is recorded against the user who ran the cell, so on a shared kernel it still lands under the right name — and it refuses rather than guessing if it cannot tell who you are.
Changing your mind
Re-opening the picker
Nothing reopens the dialog on its own once a binding works. When a token is rotated, a credential is renamed, or you simply picked the wrong one:
- Open the command palette and run "Set git credential for this repository".
- For a clone that you cancelled, there is no repository to act on — just clone again and answer the dialog.
- From a cell,
synutils.git.setCredential(...)overwrites the existing binding for that remote.
A repository can hold one HTTPS binding and one SSH binding at the same time; they are tracked separately and do not overwrite each other.
The question you asked
Workspaces and service accounts
Service accounts and git credentials are unrelated systems, and this is worth being explicit about with users who assume otherwise.
| Service account | An AWS IAM identity attached to a Notebook Workspace or Runtime Template. It governs data access — S3, Glue, Athena, Spark history. Nothing in the git authentication path consults it. |
|---|---|
| Git credential | A Syntasa credential holding a provider token or SSH key, chosen per user, per repository. It governs repository access. It works identically whether or not the workspace has a service account. |
So: a workspace running under a service account still needs each member to bind their own git credential. Adding permissions to the service account will never fix a git authentication failure, and a service account is not something you can select in the credential dropdown.
On a shared workspace
Bindings are stored one file per user under config/git-bindings/ on the workspace mount, and hold credential names only — never tokens. Each member picks their own credential; pushes from that workspace now arrive on the provider as distinct people. Anyone who relied on the old shared key will find their git access has stopped working until they bind a credential of their own; that is the one migration step to flag to teams.
When it goes wrong
Reading the failure
| What you see | What it means |
|---|---|
| The credential was refused | Either the token is wrong or expired, or the git username does not match the account it belongs to. On Bitbucket, check the username field first — a correct token with the wrong account name fails identically to a bad token. |
| The SSH key was refused | Either it is not the key registered with your account on that host, or that account has no access to the repository. |
| The repository was not found | Either the URL is wrong, or the credential has no access. Providers report a private repository you cannot see as missing rather than forbidden, on purpose. |
| Host key verification failed | Not a credential problem. The host key changed or is unknown. Picking a different credential is exactly the wrong response — verify the host before retrying. |
| The dropdown is empty | You have no Syntasa credentials your login can read. Create one in Resources → Credentials. |
| Nothing was asked, but the sidebar shows a credentials badge | The background fetch found the repository needs authentication. It deliberately does not open a modal at you — press push or pull, or run "Set git credential for this repository". |
The dialog leads with what the failure means; git's own raw text stays available under "What git reported", which is what to copy into a support ticket.
Boundaries
What this does not cover
- Shell git in a notebook cell. The credential picker is wired to the Git sidebar's clone, push, pull and fetch. A
!git cloneof a private repository in a cell has no dialog to show and will fail. Use the sidebar. - Public repositories. Unchanged — an HTTPS clone or pull of a public repo needs no credential and is never intercepted.
- Submodules on another host. Supported over HTTPS, but each host needs its own credential, and a submodule host you have not authorised is refused rather than being sent your token.
- Bindings outliving credentials. A deleted, renamed or unshared credential leaves a binding that cannot resolve. The picker drops it and asks again rather than failing at push time.