PKR-Lab

Semaphore Vault Password Integration — Implementation Plan

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/archiv/superpowers/plans/2026-05-19-semaphore-vault-password.md

Semaphore Vault Password Integration — Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Wire the Ansible Vault password into Semaphore so playbooks can decrypt vault-encrypted variables when triggered from the UI.

Architecture: A login_password key (named vault-password) is provisioned per project via the Semaphore REST API and referenced on every template via vault_key_id. The password itself is stored vault-encrypted in group_vars/all.yml and decrypted at bootstrap time.

Tech Stack: Ansible, Semaphore REST API, Ansible Vault, yamllint, ansible-lint


Files

Action Path
Modify capulus-ansible/roles/semaphore_bootstrap/defaults/main.yml
Modify capulus-ansible/roles/semaphore_bootstrap/tasks/key.yml
Modify capulus-ansible/roles/semaphore_bootstrap/tasks/template.yml
Modify (manual) capulus-ansible/group_vars/all.yml — user adds semaphore_vault_password

Task 1: Add semaphore_vault_password to group_vars

Files:

Run this on your local machine (replace YOUR-VAULT-PASSWORD with the actual password):

cd ansible
ansible-vault encrypt_string 'YOUR-VAULT-PASSWORD' --name 'semaphore_vault_password'

Expected output:

semaphore_vault_password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          38623865...

Open the vars file and paste the output at the end of the semaphore section:

make vault-edit

Add the encrypted block produced in step 1. Save and close.

cd ansible
ansible -i inventory/hosts.yml homeserver \
  -m debug -a "var=semaphore_vault_password" \
  --ask-vault-pass

Expected: the plaintext password appears as semaphore_vault_password: YOUR-VAULT-PASSWORD


Task 2: Add vault-password key to semaphore_default_keys

Files:

In capulus-ansible/roles/semaphore_bootstrap/defaults/main.yml, replace:

# Two access keys are created in every project — name them once here.
# `login` is only relevant for the ssh-type entry.
semaphore_default_keys:
  - name: semaphore-ssh-key
    type: ssh
    login: ubuntu
  - name: git-none
    type: none

with:

# Three access keys are created in every project — name them once here.
# `login` is only relevant for the ssh-type entry.
semaphore_default_keys:
  - name: semaphore-ssh-key
    type: ssh
    login: ubuntu
  - name: git-none
    type: none
  - name: vault-password
    type: login_password

Still in capulus-ansible/roles/semaphore_bootstrap/defaults/main.yml, replace:

    templates:
      - name: "Deploy Home Server"
        playbook: capulus-ansible/site.yml
        inventory: homeservers
        description: "Run the full site.yml against the home-server (recursive)."

with:

    templates:
      - name: "Deploy Home Server"
        playbook: capulus-ansible/site.yml
        inventory: homeservers
        vault_key: vault-password
        description: "Run the full site.yml against the home-server (recursive)."

And replace:

    templates:
      - name: "Deploy ugreen-paperless"
        playbook: ugreen-paperless.yml
        inventory: ugreen-nas
        description: "Provision Paperless-ngx stack on the UGREEN NAS."

with:

    templates:
      - name: "Deploy ugreen-paperless"
        playbook: ugreen-paperless.yml
        inventory: ugreen-nas
        vault_key: vault-password
        description: "Provision Paperless-ngx stack on the UGREEN NAS."
cd ansible
yamllint roles/semaphore_bootstrap/defaults/main.yml

Expected: no output (no errors)

git add capulus-ansible/roles/semaphore_bootstrap/defaults/main.yml
git commit -m "feat(semaphore): add vault-password key and wire to templates"

Task 3: Implement login_password handler in key.yml

Files:

In capulus-ansible/roles/semaphore_bootstrap/tasks/key.yml, after the last line ( - key_spec.type == "none"), append:


- name: Create login_password key in project {{ project_spec.name }}
  ansible.builtin.uri:
    url: "{{ semaphore_api_base }}/api/project/{{ project_id }}/keys"
    method: POST
    body_format: json
    body:
      name: "{{ key_spec.name }}"
      type: login_password
      project_id: "{{ project_id | int }}"
      login_password:
        login: ""
        password: "{{ semaphore_vault_password }}"
    headers:
      Cookie: "{{ semaphore_cookie }}"
    status_code: [200, 201, 204]
  no_log: true
  register: sem_vaultkey_create
  failed_when: false
  when:
    - not key_exists
    - key_spec.type == "login_password"

- name: Fail with HTTP details if vault key creation failed
  ansible.builtin.fail:
    msg: >-
      Vault key creation returned HTTP {{ sem_vaultkey_create.status }}:
      {{ sem_vaultkey_create.msg | default('no message') }}
  when:
    - not key_exists
    - key_spec.type == "login_password"
    - sem_vaultkey_create is not skipped
    - sem_vaultkey_create.status not in [200, 201, 204]
cd ansible
yamllint roles/semaphore_bootstrap/tasks/key.yml
ansible-lint roles/semaphore_bootstrap/tasks/key.yml

Expected: no errors

git add capulus-ansible/roles/semaphore_bootstrap/tasks/key.yml
git commit -m "feat(semaphore): handle login_password key type for vault password"

Task 4: Add vault_key_id to template creation

Files:

In capulus-ansible/roles/semaphore_bootstrap/tasks/template.yml, replace:

    body:
      project_id: "{{ project_id | int }}"
      inventory_id: "{{ project_inventory_map[template_spec.inventory] | int }}"
      repository_id: "{{ repository_id | int }}"
      environment_id: null
      name: "{{ template_spec.name }}"
      playbook: "{{ template_spec.playbook }}"
      arguments: "[]"
      description: "{{ template_spec.description | default('') }}"
      allow_override_args_in_task: false
      app: ansible
      git_branch: "{{ project_spec.repository.branch | default('main') }}"
      type: ""
      suppress_success_alerts: false

with:

    body:
      project_id: "{{ project_id | int }}"
      inventory_id: "{{ project_inventory_map[template_spec.inventory] | int }}"
      repository_id: "{{ repository_id | int }}"
      environment_id: null
      vault_key_id: >-
        {{ (project_key_map[template_spec.vault_key] | int)
           if (template_spec.vault_key is defined
               and template_spec.vault_key in project_key_map)
           else None }}
      name: "{{ template_spec.name }}"
      playbook: "{{ template_spec.playbook }}"
      arguments: "[]"
      description: "{{ template_spec.description | default('') }}"
      allow_override_args_in_task: false
      app: ansible
      git_branch: "{{ project_spec.repository.branch | default('main') }}"
      type: ""
      suppress_success_alerts: false
cd ansible
yamllint roles/semaphore_bootstrap/tasks/template.yml
ansible-lint roles/semaphore_bootstrap/tasks/template.yml

Expected: no errors

git add capulus-ansible/roles/semaphore_bootstrap/tasks/template.yml
git commit -m "feat(semaphore): set vault_key_id on templates from project_key_map"

Task 5: Apply and verify

make semaphore

Expected: all tasks ok or changed, no failed. The vault-password key should show
changed for both projects (first run), templates may also show changed if they need
to be recreated.

Note: If templates already exist from a previous run they will NOT be updated
(the idempotency check skips existing templates). Delete them in the Semaphore UI
first if you need vault_key_id applied to existing templates.

Open https://semaphore.homeserver → log in as admin.

For each project (home-server, ugreen-paperless):

  1. Go to Key Store — verify vault-password entry exists with type Login with password
  2. Go to Task Templates — open the template, verify Vault Password field shows vault-password

In the Semaphore UI, trigger the Deploy Home Server template with a dry-run playbook tag:


Idempotency Note

Re-running make semaphore after the initial apply is safe:

If vault_key_id needs to be updated on an already-existing template, delete the template
in the Semaphore UI and re-run make semaphore.