Git access: connection mode, Avaloi Git, and GitHub

Open your site, pick staging or a multidev in the top bar, and open Info. The first card, Code, has the development mode switch (SFTP | Git), Clone with Git, what changed since the last commit, and the commit history. Further down, Avaloi Git holds SSH keys and HTTPS tokens, and Connect an external repository links GitHub, GitLab, or Bitbucket.

Live has none of these. Live code is read only and arrives only by a deploy from staging, so live has no Git access: no clone address, SSH keys for Git, tokens, or connected repository. Live's first card is Deploys: what staging has that live lacks, Deploy to live, and the deployment history with rollback. See Staging, live, and multidev environments.

Development mode

Staging and each multidev have a mode. The SFTP | Git switch at the top of the Code card shows the current one.

Mode	What changes code
Git mode (the default for new environments)	Only Git: a push, a merge, a pull from a connected repository, a promote, or a reset from live. Code is read only everywhere else. wp-admin cannot install or update plugins or themes, and the plugin and theme editors are off. Activating and deactivating plugins still works.
SFTP mode	SFTP, SSH, wp-admin (plugin and theme installs and updates), WP-CLI, and the Files page. Click Commit changes to save the changes in Git. A Git push is pulled in when nothing is uncommitted.

New staging and multidev environments start in Git mode. Environments made before this default keep the mode they had. To switch, click the other side of the switch, then Switch to Git mode or Switch to SFTP mode. Switching to SFTP mode loses nothing: the working tree starts as a copy of the code the environment runs now. Switching to Git mode needs your uncommitted changes committed first. Avaloi says how many changes are waiting and offers Commit and switch (with a commit message) or Discard and switch. While a repository is connected, disconnect it before you switch to SFTP mode. About the two modes under the switch explains both.

Live has no switch. It is always in Git mode, and its code arrives only by a promote from staging.

Avaloi Git

Every site is a Git repository hosted by Avaloi. Clone with Git on the Code card, and the Avaloi Git card, show the clone and push address for the environment, with copy buttons:

ssh://USER@HOST:PORT/srv/git/site.git

1. Add your SSH key. Click SSH keys on the card, give the key a name, and paste your .pub file. No key yet? Run ssh-keygen -t ed25519 -C "[email protected]". The same keys work for SSH and SFTP.
2. Clone the site with the clone command, or add Avaloi as a remote to a repository you have.
3. Push to the environment's branch: main for staging, env/{name} for a multidev. In Git mode, Avaloi builds the new commit and runs it. In SFTP mode, Avaloi pulls it into the working tree when nothing is uncommitted; otherwise the card says New commits on main are waiting and offers Pull latest commits.

If the card says Not set up, click Turn on Git over SSH. If it says SSH is off, turn SSH on in the SFTP card above first. Live has no Avaloi Git card: it takes no pushes. Through the API, the Git routes on live answer 409 with the code live_is_immutable.

In SFTP mode the Code card shows how many files changed since the last commit. Write a message and click Commit changes to save them to Git with you as the author. Avaloi never commits uploads, caches, wp-config.php, or files that look like secrets. See Commit changes made over SFTP.

The Branches line lists each branch and the environments that run it.

Clone and push over HTTPS with a token

No SSH key? Use a Git access token instead. Tokens work on staging and multidevs. The first token turns HTTPS Git on for the environment, so there is no separate setup step. (HTTPS Git runs as the environment's SSH user, so SSH must be on for the environment.) The card shows the HTTPS address:

https://YOUR-ENVIRONMENT-HOSTNAME/_avaloi/git/site.git

The hostname is the environment's own Avaloi address, the one Visit site opens, such as acme-7k2p.avaloi.com. There is no shared Git hostname, so nothing to set up in DNS.

1. Under HTTPS, click Create token. Give it a name you will recognize, such as laptop or CI, and choose Read only (clone and fetch) or Read and write (also push). Tokens expire after 90 days unless you pick another length, up to a year.

2. Copy the token now. Avaloi shows it once and stores only a hash of it, so nobody at Avaloi can read it back. For a read and write token, the same dialog shows the two commands to add the remote and push.

3. Clone with the command on the card, such as git clone https://[email protected]/_avaloi/git/site.git acme, or add the remote to a repository you have and push:

   git remote add avaloi https://acme-7k2p.avaloi.com/_avaloi/git/site.git
   git push avaloi main
   

   When Git asks for a password, paste the token. The username can be anything.

A push over HTTPS works like a push over SSH: the same branch rules apply, and the environment updates by itself through the same jobs. Right after the push, Git prints what Avaloi is doing, for example:

remote: Avaloi: Push received for staging (branch main).
remote: Avaloi: Avaloi is building a release from it and will switch staging to it.
remote: Avaloi: Follow it at https://app.avaloi.com/dashboard/sites/SITE/info?env=ENV (job JOB).
remote: Avaloi: Then view staging at https://acme-7k2p.avaloi.com

The tokens table lists each token with its scope, its first characters, when it expires, when it was last used, and who made it. Click Revoke to stop a token at once (a client that already had a yes can keep working for up to a minute). Each token works for one environment only; make another for each environment you need. Every token made, used, and revoked is in the activity log.

Keep tokens out of shared files. If you put a token in a clone URL, Git saves it in .git/config; a credential helper is safer. Live has no tokens: it takes code only by a promote, and a staging token reads the same site repository.

What a push may do: it may update only the environment's branch, it may not delete a branch, and it may not rewrite history (no force push). Avaloi checks this in the repository and again when it takes the push, so a push that is refused changes nothing. Customer hooks never run: the hooks that run on a push are fixed by Avaloi.

The last push

Under the addresses, Last push shows what happened to the most recent push, over SSH or HTTPS: Updating, Updated, Waiting (staging has uncommitted changes, so click Pull latest commits), Failed, Refused, or No new commits. It lists who pushed and when, the last lines of the log, and View job opens the job.

If a push is refused

Git prints the reason after remote:. The card lists the same reasons under If a push is refused.

What Git prints	What it means	What to do
Live takes code only by a promote from staging.	You pushed to live, or with a token made for live.	Push to staging, then promote.
This token can only read.	The token is read only.	Create a token with Read and write.
This environment takes pushes to main only.	You pushed another branch.	Push to the branch the card names.
This environment takes code from ... Push there.	A GitHub or other repository is connected.	Push to that repository, or disconnect it.
this push is larger than 256 MB or HTTP 413	The push is too big. Over HTTPS the limit is 100 MB, because the request crosses Cloudflare.	Push fewer files at a time, or use Git over SSH, which has the 256 MB limit only.
Authentication failed or 403	The token is wrong, expired, revoked, or for another environment.	Make a new token. Clear the old one from your credential helper.
too many failed sign-ins	Many wrong tokens came from your address.	Wait a few minutes.

Connect an external repository

Use GitHub, GitLab, Bitbucket, or any Git host as the source of the environment's code. The environment must be in Git mode. Live never connects.

1. Add the deploy key. Click Show deploy key and add it to the repository as a read only deploy key. On GitHub: Settings, Deploy keys, Add deploy key, leave Allow write access off.
2. Connect the repository and add the webhook. Enter the repository address (such as [email protected]:acme/site.git) and the branch, then click Connect repository. Avaloi shows a webhook URL and secret. Add them to the repository: on GitHub, Settings, Webhooks, Add webhook, content type application/json, Just the push event. Copy the secret now; Avaloi shows it once.
3. Pull now. Avaloi pulls once to check the key works, then after every push to the branch.

Once connected, pushes to the Avaloi remote are refused for that environment, so there is one source of truth. Disconnect stops the pulls and leaves the code as it is.

If a pull fails because the remote branch does not contain the environment's commit, the card offers Replace with the remote branch. Avaloi keeps the old commit in case you need it.

Quick answers

Git says permission denied. Check that the key you added is the one your computer offers. Run ssh -v with the same host, port, and user to see which key it tries.

I pushed, but staging did not change. In SFTP mode, staging waits while it has uncommitted changes. Commit or discard them, then click Pull latest commits on the Avaloi Git card. If the push said "Avaloi was not told", call POST /v1/environments/{id}/git/import to check for pushes.

Can I deploy from CI? Yes. Push the built commit to the Avaloi Git remote from your CI job with an SSH key you added. A ready made GitHub Action is not published yet. See Connect GitHub, GitLab, or Bitbucket.

Git says "Authentication failed" over HTTPS. The token is wrong, expired, revoked, or made for another environment. Check the tokens table, then make a new one. Git may have saved the old token: clear it from your credential helper.

Git over HTTPS says the push was refused. The token is read only, the push went to a branch the environment does not take, a repository is connected, or the push is larger than 100 MB. The message after remote: says which. See If a push is refused.

Can I put a password on staging so only my client sees it? Yes. Open Tools, then Password protection. It asks visitors for a user name and password, stores only a hash, and is off until you turn it on. It does not affect Git: Git uses its own tokens. Staging and multidevs are already hidden from search engines. See Tool settings.

I pushed, but live did not change. Live changes only by a promote. On staging, open Info and click Promote to live in the Environment details card.

API

• GET /v1/environments/{id}/git: the mode, the Avaloi remote (SSH and HTTPS addresses), the last push with its job, and the connected repository
• PUT /v1/environments/{id}/connection-mode with {"mode": "sftp"} or {"mode": "git"}
• POST /v1/environments/{id}/git/ssh: turn on Git over SSH
• POST /v1/environments/{id}/git/import: check for pushes
• POST /v1/sites/{id}/git/deploy-key, PUT /v1/environments/{id}/git/connection, DELETE /v1/environments/{id}/git/connection?confirm=true
• POST /v1/environments/{id}/git/pull and POST /v1/environments/{id}/git/webhook-secret
• GET /v1/environments/{id}/git/tokens, POST /v1/environments/{id}/git/tokens with {"name": "laptop", "scope": "write", "expires_in_days": 90, "confirm": true} (the answer holds the token once), and DELETE /v1/environments/{id}/git/tokens/{token_id}?confirm=true
• GET /v1/environments/{id}/working-tree, POST /v1/environments/{id}/commit, POST /v1/environments/{id}/working-tree/sync
• GET /v1/environments/{id}/ssh, POST /v1/environments/{id}/ssh-keys, DELETE /v1/environments/{id}/ssh-keys/{key_id}

Related

• Deploys, rollback, and where the Code tab went
• Staging, live, and multidev environments
• How Git deploys work
• SSH and SFTP
• Connect GitHub, GitLab, or Bitbucket