Troubleshooting repository setup
Problems with your repository on GitHub. For problems with an installed app on your computer, see Troubleshooting an installed app.
Synchronisation is failing on GitHub Actions
The Sync with Template Repository workflow needs the encrypted repository secret LABCONSTRICTOR_SYNC_TOKEN because template migrations can update files in .github/workflows/. Follow the automatic template synchronization guide for the complete beginner-friendly setup.
The synchronization token is missing
Create the token and save it under Settings → Secrets and variables → Actions with this exact name:
LABCONSTRICTOR_SYNC_TOKEN
GitHub refuses to update a workflow file
If the error says GitHub is refusing to create or update a workflow without workflows permission, ensure the token has all of these repository permissions:
- Contents: Read and write
- Pull requests: Read and write
- Workflows: Read and write
Repositories created before template version 0.1.12 also need the one-time workflow edit described in the synchronization guide so the existing workflow starts using the secret.
Bad credentials or authentication failed
The token may have expired or been revoked. Create a replacement token and update the existing LABCONSTRICTOR_SYNC_TOKEN secret.
The release stops at "check_placeholders.py"
The release workflow checks, before it builds the installers, that no template placeholder (PROJECT_NAME, PYTHON_PROJ_NAME, UNDERSCORED_PROJECT_NAME, ...) is left in a file the installer ships. An installer built with one would fail on the users' computers (for example No module named 'PYTHON_PROJ_NAME' at the end of the installation).
The log of the failed step lists each file and line. Replace the placeholder there with your app's value: PYTHON_PROJ_NAME is the Python package of the app (usually its folder in src/), PROJECT_NAME the app name. For app/menuinst/Welcome.ipynb, edit .tools/templates/Welcome_template.ipynb instead: the Welcome notebook is made from it at every release. Commit, then publish the release again. See migration_0_1_23.md.
The release stops at "Installers to build"
The platforms job of the release workflow reads distribution.platforms in labconstrictor-app.yaml to decide which installers to build. It stops when the file is not valid YAML, when platforms is not a list, or when it lists none of the systems the release builds installers for: windows-x86_64, linux-x86_64, macos-arm64 and macos-x86_64. The log of the step says which. Fix labconstrictor-app.yaml (see App Centre manifest), commit, then publish the release again. See migration_0_1_24.md.
Publishing to PyPI fails
The workflow Publish the Python package to PyPI (publish_pypi.yml) runs at a release only when the repository variable PYPI_PUBLISH is true or testpypi (see Upload external code). Its first job checks and builds the package; its second job uploads it. The installers do not depend on it: a failure here leaves the release and its installers as they are.
| What you see | What to do |
|---|---|
| Both jobs are grey (skipped) | The variable is missing or has another value. It must be a variable (Settings > Secrets and variables > Actions > Variables), not a secret, named PYPI_PUBLISH, with the value true or testpypi exactly. |
invalid-publisher: valid token, but no corresponding publisher |
The trusted publisher on pypi.org (or test.pypi.org for testpypi) does not match this workflow. Check the five fields: owner, repository, workflow publish_pypi.yml, environment pypi, and the project name. Then re-run the failed job (Actions > the run > Re-run failed jobs). |
... isn't allowed to upload to project ... (403) |
The name belongs to another PyPI project that this repository is not a publisher of. If it is yours, add the publisher in that project's Publishing page; if not, choose another name= in setup.py (and distribution.pip). |
PyPI already has <name> <version> (or File already exists) |
That version was uploaded before; a version can be uploaded only once, even after it was deleted. Publish a new release with a higher version. |
There is no Python package in src/ |
Add your code as a folder with an __init__.py in src/ (see Upload external code), or delete the variable PYPI_PUBLISH. |
... also publishes to PyPI |
Another workflow of the repository uploads to PyPI too. Keep one: delete the variable PYPI_PUBLISH, or delete the other workflow. |
distribution.pip of labconstrictor-app.yaml is ..., but setup.py names the package ... |
Make the two names the same. |
PyPI refuses a package whose dependency is a URL |
setup.py lists a dependency as name @ git+https://.... Publish that dependency on PyPI and name it with a version, or move the URL to requirements.txt (the installer still installs it; the PyPI package leaves it out). |
setup.py still has the template placeholder ... |
Replace the placeholder in setup.py (the log says which), commit, and publish a new release. |
| The upload job waits | The pypi environment has required reviewers (Settings > Environments > pypi): one of them approves the upload in the run. |
After a fix, re-run the failed jobs of the run if nothing in the repository changed (a publisher fixed on pypi.org); otherwise publish a new release. See the design note of template 0.1.25.