asf-tooling commented on issue #875:
URL:
https://github.com/apache/tooling-trusted-releases/issues/875#issuecomment-4410076843
<!-- gofannon-issue-triage-bot v2 -->
**Automated triage** — analyzed at `main@2da7807a`
**Type:** `documentation` • **Classification:** `actionable` •
**Confidence:** `high`
**Application domain(s):** `web_api_infrastructure`, `shared_infrastructure`
### Summary
The issue requests documentation for GitHub workflow path configuration
options (compose, vote, finish) visible in the ATR UI. @sbp noted this will be
resolved by implementing #904 first, then documenting the section in
`atr/docs/trusted-publishing.md`. The feature itself already exists — the three
workflow path fields (`github_compose_workflow_path`,
`github_vote_workflow_path`, `github_finish_workflow_path`) are stored as JSON
lists in the database and validated to start with `.github/workflows/`. Since
the resolution is explicitly blocked on #904, no patch should be proposed here.
### Where this lives in the code today
#### `atr/models/validation.py` —
`validate_trusted_publishing_workflow_paths` (lines 109-112)
_currently does this_
Validates that all workflow paths start with '.github/workflows/',
confirming the feature exists and the constraint users should know about.
```python
def validate_trusted_publishing_workflow_paths(paths: list[str]) -> None:
for path in paths:
if not path.startswith(".github/workflows/"):
raise ValueError("GitHub workflow paths must start with
'.github/workflows/'.")
```
#### `tests/e2e/policy/helpers.py` — `textarea_github_compose_workflow_path`
(lines 38-47)
_currently does this_
Shows the three UI fields that exist for configuring workflow paths —
compose, vote, and finish — confirming the feature the user is asking about.
```python
def textarea_github_compose_workflow_path(page: Page) -> Locator:
return page.locator('textarea[name="github_compose_workflow_path"]')
def textarea_github_finish_workflow_path(page: Page) -> Locator:
return page.locator('textarea[name="github_finish_workflow_path"]')
def textarea_github_vote_workflow_path(page: Page) -> Locator:
return page.locator('textarea[name="github_vote_workflow_path"]')
```
#### `tests/unit/test_policy_update_args.py` —
`test_policy_update_args_rejects_invalid_workflow_paths` (lines 28-38)
_currently does this_
Unit test showing the three workflow path fields accept lists of strings
that must start with '.github/workflows/'.
```python
@pytest.mark.parametrize(
"field",
[
"github_compose_workflow_path",
"github_vote_workflow_path",
"github_finish_workflow_path",
],
)
def test_policy_update_args_rejects_invalid_workflow_paths(field: str) ->
None:
with pytest.raises(pydantic.ValidationError, match="must start with"):
_policy_update(**{field: ["build.yml"]})
```
#### `migrations/versions/0026_2025.09.04_eb02c4d9.py` — `upgrade` (lines
20-26)
_currently does this_
Migration that split the original single workflow_path field into three
phase-specific fields (compose, vote, finish).
```python
def upgrade() -> None:
op.execute("DROP TABLE IF EXISTS _alembic_tmp_releasepolicy")
with op.batch_alter_table("releasepolicy", schema=None) as batch_op:
batch_op.add_column(sa.Column("github_compose_workflow_path",
sa.String(), nullable=False, server_default=""))
batch_op.add_column(sa.Column("github_vote_workflow_path",
sa.String(), nullable=False, server_default=""))
batch_op.add_column(sa.Column("github_finish_workflow_path",
sa.String(), nullable=False, server_default=""))
batch_op.drop_column("github_workflow_path")
```
### Where new code would go
- `atr/docs/trusted-publishing.md` — after 'How ATR detects automated
release keys' section or as a new section before it
@sbp explicitly identified this file as where workflow paths documentation
should be added, likely as a new section explaining the three workflow path
fields and their purpose.
### Proposed approach
Per @sbp's comment, this issue is blocked on #904 being implemented first.
Once #904 is complete, documentation should be added to
`atr/docs/trusted-publishing.md` explaining: (1) what the three workflow path
fields mean (compose, vote, finish correspond to release phases where GitHub
Actions can be triggered), (2) the validation requirement that all paths must
start with `.github/workflows/`, (3) that each field accepts multiple paths
(stored as a JSON list), and (4) examples of valid values like
`.github/workflows/release-compose.yml`.
No diff is proposed here because the team has explicitly deferred
documentation to after #904 is implemented, and we don't know what additional
context or changes #904 introduces.
### Open questions
- What is issue #904 and what changes does it introduce that affect how
workflow paths should be documented?
- Do the three workflow path fields (compose, vote, finish) control which
GitHub Actions workflows are allowed to trigger the respective release phases,
or do they serve a different purpose?
- Is there additional context about the relationship between workflow paths
and the trusted publishing OIDC flow that should be documented?
### Files examined
- `atr/docs/index.md`
- `atr/models/validation.py`
- `tests/e2e/policy/helpers.py`
- `tests/unit/test_policy_update_args.py`
- `atr/docs/trusted-publishing.md`
- `migrations/versions/0026_2025.09.04_eb02c4d9.py`
- `migrations/versions/0027_2025.09.08_69e565eb.py`
- `migrations/versions/0046_2026.01.30_72330898.py`
---
*Draft from a triage agent. A human reviewer should validate before merging
any change. The agent did not run tests or verify diffs apply.*
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
