# Rehearse publishing to PyPI from GitLab

[Read this guide on KeySigner](https://keysigner.io/integrations/guides/publish-to-pypi-from-gitlab/)

Rehearse a test release from a GitLab.com project and verify that TestPyPI trusts the intended pipeline.

## Before you start

- Use a disposable TestPyPI project you can administer and a GitLab.com project. PyPI trusted publishing requires GitLab.com for this workflow.
- Have the repository namespace, project name and top-level pipeline file. If you use a release environment, use its exact name in both the publisher settings and job.
- [Check GitLab availability](https://keysigner.io/integrations/setup-requirements/#provider-availability-gitlab)
- [Check PyPI availability](https://keysigner.io/integrations/setup-requirements/#provider-availability-pypi)

## Data and access

- **Shared or checked**. GitLab.com gives the test job an identity token. TestPyPI checks the token against the configured trusted publisher before accepting the package upload.
- **Check separately**. Production PyPI has separate publisher settings. Review package ownership and any other upload credentials separately.

## Who does what

- **TestPyPI project administrator**. Registers the trusted publisher and retains access to change the project’s publishing settings.
- **GitLab maintainer**. Reviews the job and target environment and triggers the test release from the intended revision.
- **Publishing job**. Uses the identity TestPyPI associates with the registered GitLab project and pipeline. A maintainer’s separate approval does not grant publishing access.

## 1. Register the publisher on TestPyPI

Add a trusted publisher in the TestPyPI project settings. Register the GitLab namespace, project name and top-level pipeline file, plus the release environment if the job uses one.

**Check.** TestPyPI’s project settings list the namespace, project and pipeline file from your test run, plus the environment if configured.

## 2. Run the publishing job

Follow PyPI’s GitLab workflow instructions with TestPyPI as the target. Review who can change the pipeline and trigger the publishing job.

**Check.** The publishing job completes against TestPyPI. The job and pipeline link identify the intended test revision.

## 3. Verify the package version

Check that TestPyPI shows the expected version and that the job ran for the intended commit. Review the configuration before applying the same controls to the production project.

**Check.** The test registry lists the exact version produced by that revision. Open the version page instead of relying on the pipeline status alone.

## Check your result

PyPI documents this GitLab publisher for GitLab.com projects. Keep the publishing identity separate from any KeySigner approval used by a maintainer.

[How to verify your setup](https://keysigner.io/integrations/verify-a-setup/)

## If you get stuck

### TestPyPI rejects the publishing identity

Confirm that the TestPyPI publisher names the GitLab.com namespace, project, top-level pipeline file and environment that ran. Check that the job requested an identity token for the target registry.

## Tools in this guide

- [GitLab](https://keysigner.io/integrations/gitlab/)
  - [Review signed commits and verification](https://docs.gitlab.com/user/project/repository/signed_commits/)
  - [Register an authenticator for GitLab](https://docs.gitlab.com/user/profile/account/two_factor_authentication/#register-an-otp-authenticator)
- [PyPI](https://keysigner.io/integrations/pypi/)
  - [Review trusted publishing on PyPI and TestPyPI](https://docs.pypi.org/trusted-publishers/)
  - [Set up authenticator codes for PyPI](https://docs.pypi.org/your-account/two-factor-authentication/#authentication-application-totp)

## Setup instructions

- [Register a GitLab publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/)
- [Use the GitLab publishing workflow](https://docs.pypi.org/trusted-publishers/using-a-publisher/)
- [Replace a retired PyPI upload credential](https://keysigner.io/integrations/guides/replace-retired-developer-credentials/)

[More guides for this task](https://keysigner.io/integrations/tasks/review-code-and-releases/)
