You can connect sites to Git repositories, allowing you to deploy changes to your sites automatically. In Cito we map repositories 1:1 with sites in the dashboard. You can connect a repository to your site at the Create Site wizard, or, for existing sites, from the Site Settings page. Git Connect You’ll be prompted to authorise Cito to connect to your github account or organisation. From there, you can select the repository to connect, as well as the branch. By default, we clone repositories to the Document root of your site. This applies even if you use a custom docroot. Laravel, Craft CMS and Magento sites are the exception: see where your code goes. Once connected you’ll be able to view recent commits and click ‘Deploy latest’ to pull your changes automatically. Git Connected

How ‘Deploy latest’ works

When you click ‘Deploy latest’, Cito:
  1. Switches the site to the branch you selected, if it’s on a different one.
  2. Pulls the latest commits from that branch.
  3. Runs the install commands for your site type (see below).
  4. Runs npm run build, if you’ve ticked ‘Run build after deploy’.
Cito shows a message when the deploy finishes, including any errors.

Install commands

Cito runs these commands as the site user after every deploy, including the first one: The ‘Run build after deploy’ option is available for Node.js sites. It runs npm run build, and is skipped if your package.json has no build script.
On Laravel sites, php artisan migrate --force runs on every deploy, so new migrations are applied to your live database as soon as you deploy.

Where your code goes

For most sites, the repository lives in the document root. The exceptions are site types where the web server serves a subfolder of the project:
  • Laravel and Craft CMS: the repository lives in the site’s home directory, and the document root is its public or web folder.
  • Magento: the repository lives in public_html, and the document root is public_html/pub.
On the first deploy, Cito checks out the repository over whatever is already in that folder. Files that aren’t in the repository, such as .env or auth.json, are kept.

How changes reach the live site

When the repository lives in the document root, Cito prepares each deploy in a hidden copy of the site (.deploy-staging in the home directory). It pulls, runs the install commands and the build there, then swaps the copy in for the live folder. For Laravel, Craft CMS and Magento sites, Cito updates the live files directly. While the deploy runs, your site may briefly serve a mix of old and new code.
If an install command or the build fails, the new code still goes live. The message starts “Deploy succeeded but post-install failed” or “Deploy succeeded but build failed”, followed by the error. Fix the problem and deploy again, or fix it over SSH.

Node.js applications

‘Deploy latest’ doesn’t restart Node.js applications. Passenger keeps running the version already in memory until the app restarts, so after a deploy your site can serve old code, or a mix of old and new files (for example, missing assets). Restart your application after each deploy. See restarting a NodeJS application.

When a deploy stops

Cito only applies changes that follow on from what’s already on the server. A deploy stops with an error if:
  • The branch’s history has been rewritten, for example by a force-push or a rebase.
  • Files changed on the server conflict with the incoming changes.
To fix either, connect via SSH as the site user and bring the server copy back in line with the repository. For example, git fetch followed by git reset --hard origin/<branch> matches the server to the remote branch, and discards any changes made on the server.

Changing the connected repository

If you connect a different repository to a site, the next deploy deletes everything in the folder the old repository was in, including files that weren’t in the repository such as .env and uploads, then clones the new repository. For Laravel and Craft CMS sites, this is the home directory. Take a backup first.

CLI usage

Git is pre-installed by default to allow you to interact with repositories at Github, Bitbucket or other platforms. To do this you’ll need to log in via SSH. If you are using a CI system to deploy files to your website, you should ensure the credentials you use are that of the site, not the admin user. This ensures permissions are correct.
Note that cloning a repository via SSH will mean it doesn’t show up in the site settings page. We recommend connecting your repositories via the Cito dashboard first.

Document roots

The default document root on Cito servers is public_html inside your home directory. This can be changed via Site Settings if you need to.

SSH keys

You may need to add additional SSH keys to a site in order to allow external systems to connect. To do this, see SSH.

Generating a new SSH keypair

If you wish to generate a new SSH key pair, you can do so by running the following SSH command. This is useful if you are working with private repositories and need to authenticate with Github or Bitbucket to clone them to your server. Be sure to do this as the site user you’re working with; if you generate a keypair as admin you’ll need to then copy the keys to the relevant user.
You’ll be prompted for a key passphrase & location. It is safe to accept the defaults. Once you’ve done this, you can add the public key to your Github account.

Cloning a repository

To clone a git repository, navigate to your chosen repository and run:

Pulling the latest version of a repository

To pull your latest changes, run:

Additional resources

There are a number of resources available online to help you learn Git. Here are some of our favourites: