docs: add README for Weekly Odoo Timesheets action

README.md

@@ -0,0 +1,157 @@
+# Weekly Odoo Timesheets (Gitea Action)
+
+Automate weekly export of Gitea issue time tracking to Odoo via a FastAPI middleware.
+
+This action scans all tracked times in a repository for the current week window, converts them to Odoo-compatible timesheet items, and sends them to your FastAPI service.
+
+
+## How it works
+
+- Time window: The action computes the current week as Monday 00:00 to Sunday 00:00 (based on the container timezone, typically UTC). All tracked times inside this window are collected.
+- Data source: Uses the Gitea API to list repository tracked times for the period.
+- Task mapping: For each tracked time entry, the Odoo task_id is derived from the linked issue:
+  - If the issue ref contains a segment like `ticket-<number>` (e.g. `feature/ticket-123`), `<number>` is used as `task_id`.
+  - Otherwise, it falls back to the issue number (`issue.index`).
+- Payload: Sends a JSON array of items to FastAPI at `/api/v1/account_analytic_gitea_odoo`.
+- Logging: Writes logs to `action.log` inside the container and job logs in Gitea Actions.
+
+Each item looks like:
+```json
+{
+  "date": "2025-05-06",
+  "task_id": 123,
+  "gitea_username": "alice",
+  "description": "/",
+  "hour_spent": 1.5
+}
+```
+
+
+## Inputs and environment
+
+The action defines the following inputs (see `action.yml`):
+
+- fastapi-base-url (required): Base URL of your FastAPI server (e.g. `https://api.example.com`).
+- gitea-base-url (optional): Base URL of your Gitea instance. Note: the current action image defaults to `https://gitea.ethumada.com`.
+
+Environment passed to the container:
+- FASTAPI_BASE_URL: from `inputs.fastapi-base-url`
+- GITEA_BASE_URL: hardcoded to `https://gitea.ethumada.com` (used only for presence check)
+- REPO_OWNER, REPO_NAME: from the event repository context
+- GITEA_TOKEN: from `secrets.GITEA_TOKEN`
+
+Internal default used by the binary:
+- GITEA_API_BASE_URL: if not provided, defaults to `https://gitea.ethumada.com` for the Gitea SDK client.
+
+To override the API base URL (if your Gitea instance differs), set an environment variable in the step:
+```yaml
+- name: Send Weekly Timesheets to Odoo
+  uses: https://gitea.ethumada.com/gitea/export-issue-tracked-times
+  env:
+    GITEA_API_BASE_URL: https://gitea.example.com
+  with:
+    fastapi-base-url: ${{ secrets.FASTAPI_BASE_URL }}
+```
+
+
+## Requirements
+
+- Gitea with Actions and time tracking enabled
+- A FastAPI middleware exposing the endpoint below and handling authentication to Odoo
+- Repository secret: `GITEA_TOKEN` (personal access token with repo scope) for reading time tracking via the API
+- Repository secret: `FASTAPI_BASE_URL` (the base URL of your FastAPI server)
+
+
+## FastAPI contract
+
+The action will POST to:
+- URL: `${FASTAPI_BASE_URL}/api/v1/account_analytic_gitea_odoo`
+- Method: POST
+- Body: JSON array of items (see example above)
+
+Example array payload:
+```json
+[
+  {
+    "date": "2025-05-06",
+    "task_id": 123,
+    "gitea_username": "alice",
+    "description": "/",
+    "hour_spent": 1.5
+  },
+  {
+    "date": "2025-05-07",
+    "task_id": 456,
+    "gitea_username": "bob",
+    "description": "/",
+    "hour_spent": 2.0
+  }
+]
+```
+
+Your FastAPI service should map `gitea_username` to the correct Odoo user and create or aggregate timesheet lines accordingly.
+
+
+## Usage
+
+You can schedule a weekly run or trigger it manually.
+
+Scheduled weekly run (example from `use-gitea-odoo-actions/.gitea/workflows/weekly-timesheets.yaml`):
+```yaml
+name: Send Weekly Timesheets to Odoo
+
+on:
+  schedule:
+    # Saturday 10:00 UTC (example). Adjust to your timezone/cutoff needs.
+    - cron: '0 10 * * 6'
+  workflow_dispatch:
+
+jobs:
+  weekly-timesheets:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v3
+      - name: Send Weekly Timesheets to Odoo
+        # If you use the published action in your instance:
+        uses: https://gitea.ethumada.com/gitea/export-issue-tracked-times
+        with:
+          fastapi-base-url: ${{ secrets.FASTAPI_BASE_URL }}
+```
+
+If you have this repo checked out locally or mirrored in your Gitea instance under a different slug (e.g. `gitea/weekly-odoo-timesheets`), adjust the `uses:` URL accordingly, for example:
+```yaml
+uses: https://gitea.ethumada.com/gitea/weekly-odoo-timesheets@v1
+```
+
+
+## Notes and caveats
+
+- Timezone: The weekly window uses the container timezone (alpine default is UTC). If you expect a different cutoff (e.g., UTC+3), adjust your cron schedule so the run occurs after the desired week end, or rebuild the image with your TZ.
+- Gitea API URL: The optional input `gitea-base-url` is not currently wired to the binary; to change the API base URL used by the SDK, set `GITEA_API_BASE_URL` in your workflow step.
+- Ticket parsing: The action looks for a `ticket-<id>` segment in the issue ref (e.g., branch or ref like `feature/ticket-123`). If absent, it uses the issue number as a fallback task_id.
+- Idempotency: If you run the action multiple times for the same week, your FastAPI/Odoo logic should de-duplicate or upsert as needed.
+- Error handling: Non-2xx responses from FastAPI cause the action to fail. Check `action.log` in artifacts and server logs for details.
+
+
+## Troubleshooting
+
+- No timesheets sent:
+  - Ensure time tracking is enabled and entries exist for the period.
+  - Verify `GITEA_TOKEN` has repo scope and the API URL is reachable.
+- Wrong task_id values:
+  - Confirm your issues carry a ref containing `ticket-<id>`; otherwise, the issue number will be used.
+- FastAPI errors:
+  - Confirm endpoint path (`/api/v1/account_analytic_gitea_odoo`) and payload array format.
+  - Check authentication and username-to-Odoo mapping on the server side.
+
+
+## Build details
+
+- Language: Go 1.23.x (static binary; CGO disabled)
+- Container: alpine:3.20
+
+
+## License
+
+Please refer to the repository license.