Alias listed but cannot be used

Question

I am using Drupal 9.x now and using Drush 10.x. I have always used drush aliases to manage my D7 sites as it makes life so much easier with various environments etc.

To test the newer YAML file (Drush for my old D7 uses a php file), I created a single Drush alias for a uat environment. The file, local.site.yml, is located in my ~/.drush/sites directory. When I do a drush sa to check what aliases exist, I correctly (I think?!) get the following message:

'@local.uat':

root: /var/www/my_site/web
uri: 'https://mysite.mydomain.com'

So I think this tells me that the single alias has been found.

When I try to use the alias using drush @local.uat status it fails:

[preflight] The alias @local.uat could not be found.

It must be simple... I have tried using just @uat and @site.uat but nothing works (and I would not expect it to!). Any ideas?! I am running Ubuntu 22.04 and Drush 10.6.2 if that makes a difference.

Answer 1

The filepath should be drush/sites/self.site.yml, and the contents should be the following (Indenting must be exact):

local.uat:
  root: /var/www/my_site/web
  uri: 'https://mysite.mydomain.com'

After which you will be able to call drush @local.uat.

Answer 2

Add an alias file called $PROJECT/drush/sites/self.site.yml, where $PROJECT is the project root (location of composer.json file). The site alias file should be named self.site.yml because this name is special, and is used to define the different environments (usually remote) of the current Drupal site.

The contents of the alias file should look something like the example below:

# File: self.site.yml
live:
  host: server.domain.com
  user: www-admin
  root: /other/path/to/live/drupal
  uri: http://example.com
stage:
  host: server.domain.com
  user: www-admin
  root: /other/path/to/stage/drupal
  uri: http://stage.example.com

The top-level element names (live and stage in the example above) are used to identify the different environments available for this site. These may be used on the command line to select a different target environment to operate on by prepending an @ character, e.g. @live or @stage.

Following these steps, a cache:rebuild on the live environment would be:

  $ drush @live cache:rebuild

Answer 3

OK - I finally got to the bottom of this and it is working.

In order to get this to work all I needed to do was add the path of ANY alias file or files to each project's Drush config file i.e. drush.yml as well as my own local one.

You can name it whatever you like, self.site.yml or foo.site.yml if you wish, there is no need for a special first name, all you need is myname.site.yml. I have tested this and created two identical alias files with different names:

self.site.yml

foo.site.yml

Both or these files reside in my ~/.drush directory but that is also not important as long as the path is defined in drush.yml in both your local drush installation AND in each project. Remember, you may have different versions of Drush per project.

When I do drush sa:

'@foo.foo':
  root: /var/www/my_site/web
  uri: 'https://mysite.mydomain.com

'@self.uat':
  root: /var/www/my_site/web
  uri: 'https://my_site'

Both drush @uat status and drush @foo status work equally well as they point to the same Drupal root.

The location of the sites aliases file also makes no difference. Changing the location of my sites alias path to 'bar' instead of drush or .drush is fine as long as the local and project drush.yml are aligned. This is how it looks in all my drush.yml files now:

  paths:
    alias-path:
      - '${env.HOME}/.drush/sites'

I could equally have used ${env.HOME}/.drush/sites, ${env.HOME}/drush/sites or ${env.HOME}/bar/sites

I hope this helps others!