the role will not be autodownloaded, this still needs to happen by invoking ansible-galaxy, we should really make that clearer in the docs (though it is a feature we do want).

Ah okay. Yeah, that's confusing, because the fact that it allows you to put a URL suggests that it might download it for you even though it doesn't actually say that. Why else would you put a URL instead of just the name of the role if it wasn't doing something over the network (rhetorical question)?

Would love to be able to autodownload roles from galaxy or github.

It would event be pretty good if you could just pop a requirements.yml file in the playbook directory and ansible would automatically do ansible-galaxy install -r requirements.yml. This is what I ended up doing in my case, though I do it in a separate step from a Python wrapper that we have around ansible-playbook. As it stands, you can't even put ansible-galaxy install -r requirements.yml in the same playbook as the one that uses the role, because during playbook verification, ansible will complain about the missing role and this occurs before it can execute ansible-galaxy. I guess another way to solve this is if there was some way to specify special tasks in a playbook that get run before verification, which I imagine is probably hard and/or doesn't make sense to the way that Ansible works, but I'll throw it out there just in case.

+1 to clearing this up. It is super confusing. I wasted a day on it. As far as I can tell ansible-galaxy cannot download roles from a git repo. Only through the ansible-galaxy api. Is that right?

ansible-galaxy is able to download roles from any git/mercurial repo

Another way to solve things is if ansible allowed you to install roles with pip. Then one could have a requirements file with ansible and all the necessary roles.