  Rare-earth (RE) doped GaN is of interest for optoelectronics and spintronics
and potentially for quantum applications. A fundamental understanding of the
interaction between RE dopants and the semiconductor host is key to realizing
the material's full potential. This work reports an investigation of lanthanide
($Ln$) defects in GaN using hybrid density-functional defect calculations. We
find that all the $Ln$ dopants incorporated at the Ga lattice site, $Ln_{\rm
Ga}$ ($Ln$ = La--Lu), are stable as trivalent ions, but Eu and Yb can also be
stabilized as divalent and Ce, Pr, and Tb as tetravalent. The location of
$Ln$-related defect levels and the $Ln$ $4f$ states in the energy spectrum of
the host material is determined from first principles. We elucidate the
interplay between defect formation and electronic structure, including the
$Ln$--N interaction, and the effect of doping on the local lattice environment.
Optical properties are investigated by considering possible defect-to-band and
band-to-defect transitions involving $Ln_{\rm Ga}$ defects with in-gap energy
levels, including broad "charge-transfer" transitions. These defects can also
act as carrier traps and mediate energy transfer from the host into the
$4f$-electron core of the $Ln$ ion which leads to sharp intra-$f$ luminescence.
