First steps

this is for getting semaphore to do some initial work, to test. for simplicity we assume, that you use the same SSH-key to checkout from git and connect to the machines

warning:

• if you access semaphore over http, and input a private key, that's rather unsecure. so either put a https proxy in front, or do this over a trusted network

prerequisites:

• basic understanding of git, ssh, ssh-key-pairs and ansible
• installed semaphore & logged into it's webinterface
• you have created a new ssh-key-pair for ansible
• you have some ansible code in a git-repository,
• you can clone the git-repo manually on the command line, with your ssh-key
• you have a test-target-server, and can connect to it from the machine semaphore is running on, with your ssh-key

how to run a playbook with semaphore:

• on the dashboard, create a project, click on it's name on the dashboard
• go to 'Key Store', create a key, select keytype 'SSH Key' and fill in both public & private part of your ssh-key
• go to 'Playbook Repositories', create a repository, choose your just created SSH Key, and enter the repository url/address (if you enter a https-git-url, which asks for a password if you do it on the command line, it won't work with semaphore)
• go to 'Inventory', create a inventory, select your ssh key, type static
• then edit inventory content, and enter your test-target-server
• create an empty environment { } named 'production'
• go to 'Task Templates', create a new template, give it any alias, and now you combine all the parts you just created:
  • Playbook Name --> filename of your playbook within your git-repo
  • SSH Key --> your just created ssh-key
  • Inventory --> your just create inventory
  • Playbook Repository --> your just created repository
  • Environment --> your just created environment
  • Extra CLI Arguments --> can be left blank
  • Override semaphore arguments --> can be left unchecked
• finally press run, (you can enable debug later to get much more output) and run!

now semaphore will try to checkout your code, and run ansible with it. good luck.

you most likely run into some troubles. enable debug and try to do stuff manually to see whats happening.

how to install collections and roles

• Collections and roles are installed with a requirements file. Ansible Galaxy Documentation
• Semaphore is looking into the roles folder of the project root. Place your requirements file there: ./roles/requirements.yml
• If you want to install collections and roles only for this Project use the roles_path and collections_paths variable in your ansible.cfg config.

[defaults]
# Installs collections into [current dir]/ansible_collections/namespace/collection_name
collections_paths = ./

# Installs roles into [current dir]/roles/namespace.rolename
roles_path = ./roles

Troubleshooting

some thing goes wrong, it's unclear what semaphore is doing

---> look at the code of semaphore. it very clear readable go, and not a big codebase, so its easy to find stuff

you can ssh to the git repo, but git clone fails with 'permission denied'

As semaphore rely on GIT_SSH_COMMAND environment variable, which was introduced in git 2.3.0,

---> update git to a more recent version!