1.4. Common Steps#

This section describes the installation steps that are common to both new and existing repositories. Follow these steps when you are asked to do so in the respective installation guides:

  1. Add a Personal Access Token (PAT) to the repository.

  2. Activate trusted publishing (OIDC) for PyPI and TestPyPI.

  3. Create a Codecov account and install the Codecov GitHub app.

  4. Add a Zenodo token to the repository.

1.4.1. GitHub PAT#

The repository owner (or a member with admin permissions to the repository) needs to create a PAT with the required permissions, and store it as a secret in the repository.

Why a PAT is Required

PyPackIT works by interacting with your repository and performing various tasks on your behalf. To be allowed to do so, PyPackIT needs a token to authenticate with GitHub. By default, GitHub automatically creates a unique GITHUB_TOKEN at the beginning of each workflow run, to be used by the workflow to authenticate with GitHub. However, this token has limited permissions by design, and is not sufficient for PyPackIT to perform all its tasks, such as modifying the repository’s settings. Therefore, the PAT is used instead of the GITHUB_TOKEN to perform tasks that require higher permissions.

To add a fine-grained personal access token to your repository:

  1. Click here or alternatively in your GitHub user account, navigate to Settings > Developer settings > Personal access tokens > Fine-grained tokens > Generate new token.

  2. Under Token name, enter a name for your token (e.g. <YOUR-REPO-NAME>_REPODYNAMICS_ADMIN_TOKEN), and choose an expiration date under Expiration. Note that you have to repeat these steps to replace the token after it expires.

  3. Under Repository access choose Only select repositories and then select your new repository from the dropdown menu.

  4. Under Permissions select Repository permissions and set the Administration, Contents, and Pages access to Read and write.

  5. Click on the Generate token button at the bottom of the page.

  6. Copy the displayed token to your clipboard.

  7. Go to Settings > Security > Secrets and variables > Actions > Secrets > New repository secret in your repository.

  8. In the Name field, enter REPO_ADMIN_TOKEN, paste the token you copied in step 6 into the Secret field, and click on the Add secret button.

For Organization-Owned Repositories

If your repository is owned by an organization (as opposed to a personal account), your organization must allow GitHub Actions to create pull requests. This can be set in the organization account under Settings > Actions > General > Workflow permissions, by enabling the option Allow GitHub Actions to create and approve pull requests.

1.4.2. PyPI Trusted Publishing#

PyPackIT uses trusted publishing (OIDC) to automatically authenticate with PyPI servers and publish your Python package on TestPyPI and PyPI, without the need to manually set authentication credentials such as username and password (cf. PyPI docs and GiHub docs).

To activate trusted publishing for both PyPI and TestPyPI in your respective accounts:

  1. Create an account on PyPI or log in to your existing account.

  2. If you have not published this project to PyPI before, go to the Publishing page of your account and navigate to the Add a new pending publisher section at the bottom of the page. Alternatively, if you have already published this project to PyPI, go to the Your projects page of your account, find your project and click on the Manage button, then go to the Publishing tab and navigate to the Add a new publisher section at the bottom of the page.

  3. Fill in the fields in the trusted publishing form for GitHub with following data:

    1. PyPI Project Name (only for new projects): Distribution name of your Python package as given in the $.pkg.name field of your project’s metadata. If you haven’t specifically defined a package name, this will be the automatically derived package name as described in the installation guide.

    2. Owner: GitHub username or organization name that owns the repository.

    3. Reposiroty name: Name of your GitHub repository.

    4. Workflow name: _pkg_publish.yaml

    5. Environment name: PyPI

  4. Click on the Add button to submit the form. Make sure the submission is accepted by checking the response message that appears at the top of the page. If the submission is rejected due to a name conflict, you have to try a different name for the project. In that case, don’t forget to update your package name in the project metadata (and/or rename your repository) afterwards.

  5. Repeat the above steps in your TestPyPI account, only this time under the Environment name field enter TestPyPI instead of PyPI.

1.4.3. CodeCov Account#

  1. Create an account on CodeCov using your GitHub account.

  2. Install the Codecov GitHub app either by clicking on the Configure Codecov’s GitHub app link on the Codecov website, or directly from the app page. You can choose to install it for all your repositories or only for the current repository.

1.4.4. Zenodo Token#

  1. Create an account on Zenodo or log in to your existing account.

  2. In the Applications page of your account, click on New token under the Personal access tokens panel.

  3. Add a Name (e.g., name of your GitHub repository), select deposit:actions under Scopes, and click on the Create button.

  4. Copy the displayed token to your clipboard, and then click on the Save button.

  5. Go to Settings > Security > Secrets and variables > Actions > Secrets > New repository secret in your repository.

  6. In the Name field, enter ZENODO_TOKEN, paste the token you copied in step 4 into the Secret field, and click on the Add secret button.

  7. Repeat the above steps for Zenodo Sandbox, only this time in step 6, enter ZENODO_SANDBOX_TOKEN instead of ZENODO_TOKEN.

For Existing Projects

If your project is already published on either Zenodo or Zenodo Sandbox and you wish to publish future versions under the same so-called concept record (instead of creating a new concept), you can add your existing concept’s DOI and ID to the variables files in your repository. Note that this must be done in the first commit after adding your tokens, otherwise a new concept will be created for each platform (Zenodo or Zenodo Sandbox) that does not define an ID.

On this page

Last updated on Nov 20, 2024.

Edit on GitHub