# 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.