From 74518f1534ec0728976c35f7c9c425d51a14a50d Mon Sep 17 00:00:00 2001 From: Mandresy RABENJAHARISON Date: Tue, 16 Sep 2025 15:08:04 +0300 Subject: [PATCH] docs: add README for Weekly Odoo Timesheets action --- README.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ae82f35 --- /dev/null +++ b/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-` (e.g. `feature/ticket-123`), `` 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-` 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-`; 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.