elastic / elastic/docs-actions

Enable changelog commits on fork PR branches via service-account PAT

Open
#129 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
5
Forks
9
Avg merge
1d 21h
Merged PRs (30d)
30

Description

## Background

`changelog/submit/evaluate` currently forces `can_commit=false` for all fork PRs, regardless of `maintainer_can_modify`, because the workflow's `GITHUB_TOKEN`:

- Is scoped to the upstream repository only.
- Does not inherit the `maintainer_can_modify` privilege — that is a feature for *human* upstream maintainers, not bot tokens.

As a result, fork PRs can only ever receive the changelog as a PR comment; we cannot push a changelog commit to the fork's PR branch with `GITHUB_TOKEN`.

This was discovered while wiring up `elastic/cloud` (a private repo) to the changelog workflow — the trusted-fork checkout failed because `GITHUB_TOKEN` cannot read the private fork either. That part is now worked around by checking out via `refs/pull/N/head` from the upstream; the push side is the remaining gap.

## Proposed approach

Accept an opt-in service-account PAT through the existing `github-token` input on `changelog-submit.yml`. When provided, the strategy step would set `can_commit=true` even for fork PRs, and the apply step's existing fork-push branch becomes the active path.

A PAT belonging to a user with write access to the upstream *can* push to fork PR branches via `maintainer_can_modify`, where `GITHUB_TOKEN` cannot.

### Why not a GitHub App?

A GitHub App's installation token is scoped to the repos the App is installed on. To push to `/`, the App would need to be installed on every contributor's fork — impractical for open contribution. Apps installed only on the upstream do *not* inherit `maintainer_can_modify` either. PAT is the only practical path that doesn't require fork-owner action.

## Setup needed (process)

1. Identify (or provision) a service-account user with write access to each opted-in upstream repo. Likely `elasticmachine` or a dedicated `elastic-docs-bot`.
2. Generate a fine-grained PAT scoped to `contents:write` + `pull-requests:write` on those repos.
3. Store the PAT as a repo or org secret in each opted-in repo.
4. Document the new opt-in input on the reusable workflow.

## Implementation sketch

- Add an `enable-fork-commits` boolean input (default `false`) to `changelog-submit.yml` and `changelog/submit/evaluate`.
- When `enable-fork-commits == true` AND a non-default `github-token` is provided, set `can_commit=true` for org-member fork PRs with `maintainer_can_modify=true`.
- The existing fork-push code path in `changelog/submit/apply` already handles the actual push; it just needs the surrounding gating to allow it through.
- Update the README "Comment-only mode" section to describe the opt-in path and the PAT requirements.

## Out of scope for this issue

- The temporary workaround forcing `can_commit=false` for forks — already in place, see #TBD.
- The `refs/pull/N/head` checkout swap that fixed the read side — already in place, see #TBD.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.