Token & Config Scope Documentation


I just wanted to start a discussion here so that it’s in writing somewhere on the interwebs. I’ve been looking at the docs and experimenting with the token behaviours and it was confusing for me. Not trying to say it’s bad behaviour. It’s just that for some reason it didn’t click at first and the docs didn’t specify.

Lets say you have a clean (meaning no doppler yet) 3 tiers directory:

    - dir1
    - dir2
        - dir2a

So I’m just gonna write the rules here, in an unordered list, that I think should be included in the Docs.

  • As stated, Token scopes and Project/Config scopes must match. (obviously)

  • A child directory will inherit from the nearest parent with a declared configuration

      - If you apply a service token to dir2 and run setup, dir2a inherits the configuration of dir2
      - If you apply a different token and setup to DIR, then dir1 will inherit but not dir2 as it has its own configuration
      - if you move dir2a under dir1, dir2a will inherit its token and configs from dir1 which inherits from DIR.
  • Tokens and Configs don’t move with directories

(I believe this happens because the doppler tracking system is external to the repo and movements are hard to track)

    - If you configure dir2a with a unique token and project/config, then move dir2a back to dir1 then 'doppler run' will not work
   - but if you move dir2a back to dir1 where it was previously declared it's as if the directory was never moved.
   - If you replace the directory with a directory of the same name then it will aquire the privilages of the previous directory. (This seems like an attack surface somehow to me)

Please let me know if I’ve misunderstood anything here or have it plain wrong.

In regards to tokens and configs not moving with directories, I was wondering if anyone knows of a way to maybe like ‘doppler mv’ or ‘doppler cp’ a directory to a new location so that it automatically sets up the configuration in the new location and removes it config data from the old path?

1 Like

Hi @JesseRigon!

Your description of how this works is correct! The reason why it works like this is because Doppler doesn’t leave or reference any kind of file in the directories you run doppler setup in. Instead, when you run doppler setup it creates an entry in ~/.doppler/.doppler.yaml for the path you were at when you performed the setup (note: this file is never meant to be edited by hand). This creates a scope entry specifying which project and config should be used at that scope (i.e., path). Simply moving the directory doesn’t update that information. This also explains why creating a new directory at the same location of a previously setup directory inherits its configuration.

For now, if you move a directory like you mentioned, then you’ll need to run doppler setup again inside that directory. Your idea about a doppler mv or doppler cp is interesting. I’ll pass that along to our Product team for consideration. I’ll also take a look at our docs to see about updating it to explain this behavior better.


@JesseRigon As a quick follow-up – where in the documentation were you expecting to find this information described? The Service Token page is really more geared toward explaining how those work and what you’re asking about here is really more a CLI project management issue and isn’t really related to tokens directly. That said – was it the Service Tokens page you were expecting to see this information on?

I would consider this 2 separate things actually. so how the tokens and configs function together could be a new docs page in itself. something like “Managing Secrets” alongside accessing secrets amd setting secrets pages.

but if any specific commands were to be implemented such as doppler mv then I would also include that into the cli page as well, but that page currently is more geared towards a general overview of the cli and doesnt really get specific too much.

in the end, I think as a new “managing secrets” page or as am extension to the “accessing secrets” page makes the most sense to me.

@JesseRigon Is this what you’d be expecting? Secrets Setup Guide

Yeah this is much more clear to me. specifically the hint block used.

That addresses all the points I mentioned. the only thing I might add which is different but adjacent is a reference to and link to local doppler.yaml file feature. while not strictly necessary, I do feel it completes the picture.