vikunja-find

A Forgejo action that searches for a Vikunja task by a reference embedded in its description. Use it to locate tasks linked to git issues, PRs, or repos.

How it works

The action searches task descriptions for a reference string (typically a Forgejo URL) using the Vikunja API. It finds tasks whether the link was added automatically by vikunja-task or pasted manually into the description.

Usage

Find a task linked to a Forgejo issue

- uses: actions/vikunja-find@main
  id: find
  with:
    reference: "${{ github.server_url }}/${{ github.repository }}/issues/${{ github.event.issue.number }}"
    project: ${{ secrets.VIKUNJA_PROJECT }}
    api-url: ${{ secrets.VIKUNJA_API_URL }}
    api-token: ${{ secrets.VIKUNJA_API_TOKEN }}

- name: Do something with the task
  if: steps.find.outputs.found == 'true'
  run: echo "Found task ${{ steps.find.outputs.task-id }} at ${{ steps.find.outputs.task-url }}"

Find by short reference

- uses: actions/vikunja-find@main
  id: find
  with:
    reference: "myorg/myrepo#42"
    project: ${{ secrets.VIKUNJA_PROJECT }}
    api-url: ${{ secrets.VIKUNJA_API_URL }}
    api-token: ${{ secrets.VIKUNJA_API_TOKEN }}

Search all projects

Omit the project input to search across all your Vikunja tasks:

- uses: actions/vikunja-find@main
  id: find
  with:
    reference: "${{ github.server_url }}/${{ github.repository }}/issues/${{ github.event.issue.number }}"
    api-url: ${{ secrets.VIKUNJA_API_URL }}
    api-token: ${{ secrets.VIKUNJA_API_TOKEN }}

Check before creating (avoid duplicates)

- uses: actions/vikunja-find@main
  id: find
  with:
    reference: "${{ github.server_url }}/${{ github.repository }}/issues/${{ github.event.issue.number }}"
    project: ${{ secrets.VIKUNJA_PROJECT }}
    api-url: ${{ secrets.VIKUNJA_API_URL }}
    api-token: ${{ secrets.VIKUNJA_API_TOKEN }}

- uses: actions/vikunja-task@main
  if: steps.find.outputs.found == 'false'
  with:
    title: "${{ github.event.issue.title }}"
    reference: "${{ github.server_url }}/${{ github.repository }}/issues/${{ github.event.issue.number }}"
    project: ${{ secrets.VIKUNJA_PROJECT }}
    api-url: ${{ secrets.VIKUNJA_API_URL }}
    api-token: ${{ secrets.VIKUNJA_API_TOKEN }}

Inputs

Input	Required	Description
reference	Yes	Search text -- full Forgejo URL or short ref like owner/repo#42
project	No	Project name to scope the search. Omit to search all tasks.
api-url	Yes	Vikunja base URL (e.g. https://todo.example.com)
api-token	Yes	Vikunja API token

Outputs

Output	Description
task-id	Numeric ID of the found task (empty if not found)
task-url	Full URL to the task in the Vikunja web UI (empty if not found)
found	"true" if a matching task was found, "false" otherwise

Secret cascade

Like vikunja-task, secrets cascade from org to repo level via Forgejo's built-in secret resolution:

api-url: ${{ secrets.VIKUNJA_API_URL }}    # set once at org level
api-token: ${{ secrets.VIKUNJA_API_TOKEN }}  # set once at org level
project: ${{ secrets.VIKUNJA_PROJECT }}      # override per org or repo

Requirements

Runners must have curl, jq, bash, and git available. The alpine:latest container with apk add --no-cache git curl jq bash works.