The gh-pages
branch is automatically created and updated by the reports.yml
workflow. If the branch does not exist yet, run the workflow manually once or wait for the first push to main
.
Repository Setup
To fully utilize the automation and documentation features provided by FastForward DevTools, consumer repositories require specific configurations in GitHub.
GitHub Pages
FastForward DevTools automatically generates and deploys reports, test coverage, and API documentation to GitHub Pages.
- Navigate to your repository on GitHub.
- Go to Settings > Pages .
- Under Build and deployment
> Branch
:
Select the ``gh-pages`` branch.
Select
/ (root)as the folder. * Click Save .
GitHub Wiki
Normal sync generates local API Markdown in .dev-tools/wiki-generated
without a submodule. The direct Wiki workflow generates a read-only artifact on
pull requests and publishes directly from main
to the separate GitHub Wiki
repository.
Initial Manual Step Required
GitHub does not create the underlying Wiki repository until at least one
page is created via the web interface. Create an initial Home
page before
automated publication or legacy wiki --init
. Local Markdown generation
does not require this remote initialization.
- Navigate to your repository on GitHub.
- Click the Wiki tab.
- Click Create the first page (or New Page ).
- Ensure the title is
Homeand add some initial content. - Click Save Page .
Once this is done, the direct workflow can clone the separate Wiki repository
for publication. Only legacy users who explicitly choose wiki --init
need
a local submodule.
Workflow Permissions
GitHub Actions must have permission to push changes to your repository and, for the changelog release flow, to open release-preparation pull requests.
- Go to Settings > Actions > General .
- Scroll down to Workflow permissions .
- Select Read and write permissions .
- Enable Allow GitHub Actions to create and approve pull requests .
- Click Save .
Publication jobs need their declared write permissions. The external Changelog caller needs permission to open its managed version PR, but automatically publishes the tag and Release after its reviewed managed version PR is merged. Preserve any reviewed GitHub App/token policy instead of broadening every workflow token.
If the permission controls are disabled or grayed out, the repository is usually constrained by organization policy or by missing admin access. This is separate from branch protection. Branch protection affects whether the generated release pull request can be merged, while workflow permissions affect whether GitHub Actions can create that pull request at all.