Skip to content

Site Tags

A "tag" is a type of metadata that can be set on site resources. They can be used to group or filter multiple sites with in a ddev-live list sites command using the --tag flag. They are also useful and visible when describing a site using the ddev-live describe site command, visible under the Tags: heading.

A <tag> can be defined two different ways, either as a <key>:<value> pair, or simply a <key>.

Note

the tags "<key>" AND "<key>:true" are equivalent

There are a few input restrictions for a tag <key> and/or <value>:

  • a 1-40 character length range
  • must start AND end with an alphanumeric character
  • must ONLY consist of alphanumeric characters, '-', '_' or '.'

Working with Tags on DDEV-Live CLI

Prerequisites

The minimum required CLI version needed to utilize tags is v0.7.0.
For help installing or updating the DDEV-Live CLI, see Getting Started

Creating sites with tags

When creating a new site, you can apply tag(s) to the site by including the --tag flag, followed by a comma-separated list of tags. For example:

ddev-live create site (drupal || typo3 || wordpress ) ... --tag dev
ddev-live create site (drupal || typo3 || wordpress ) ... --tag dev,customer:xyz,repo:ddev

Updating or adding tags to existing sites

You can add new tag(s) or update existing tag(s) on an existing site using ddev-live config tag set .... For example:

ddev-live config tag set my-site staging
ddev-live config tag set my-site staging,customer:xyz,repo:ddev

Removing a tag

You can remove tag(s) on an existing site using ddev-live config tag unset ... and providing a set of tag keys to remove. For example:

ddev-live config tag unset my-site env
ddev-live config tag unset my-site env,customer,repo

NOTE: when removing tags, only <key> needs to be specified.
If for example a site my-site has the tag env:staging, the following command will remove it:
ddev-live config tag unset my-site env

Filtering site lists using tags

You can use one or more tags as filters when listing sites by using ddev-live list sites ... --tag.

ddev-live list sites --tag dev
ddev-live list sites --tag dev,repo:ddev

Viewing site tags

You can view the tags of a site in its describe output. For example:

ddev-live describe site my-site

SITE INFO
 Name:          my-site
 Org:           ddev-demo
 Tags:
  - staging
  - customer:ddev
...

Last update: 2020-10-19