Building and Testing Python

This guide shows you how to build Python projects with TeamCity, and it is recommended for developers completely new to TeamCity.

Prerequisites

We recommend that you have a basic understanding of Python and PyTest.

For more information, browse the Python documentation.

Step 1 – Create a TeamCity project

  1. Click the Administration cog in the top right-hand corner of the TeamCity page.
  2. Click + Create Project and select the From a repository URL tab. In the Repository URL field, enter your repository, for example: https://github.com/marcobehlerjetbrains/teamcity-python.git. TeamCity handles all popular version control systems out of the box: Git, Subversion, Mercurial, Perforce, and TFS (TeamCity Cloud + On-Premises). CVS, StarTeam, and Visual SourceSafe support is only available in TeamCity On-Premises.
  3. If your repository requires authentication, enter your username and password / access token.
  4. Click Proceed.

If TeamCity successfully connects to your repository, you will see the following dialog.

In the Create Project From URL dialog you have the option to change the project name and initial build configuration name.

Note: In newer versions of TeamCity you will also see the default branch and branch specification fields, which allow you to specify which branches TeamCity should build. Ignore those for now.

  • TeamCity will suggest a default project name, but you can choose a more suitable name for your project if you wish.
  • TeamCity will also suggest a default build configuration name. It’s fine to leave the default here, and you can change it later if you need to. (Every TeamCity project consists of at least one build configuration, which contains all the steps needed to build your project. TeamCity’s build configurations are often called jobs in other CI systems.)
  • Click Proceed.

After you click Proceed, TeamCity automatically scans your version control repository for supported technologies, in this case Python.

When TeamCity detects a .py file in your repository, it will automatically suggest one or more build steps for your project. For the repository used in this tutorial, those auto-detected build steps would run your main.py or setup.py files, which might not be what you want.

Rather, it makes sense to have the following build steps added to your Python project as a default:

  1. A Linting build step, executing Flake8 or PyLint
  2. A Testing build step, executing PyTest or UnitTest.

Instead of choosing one of the auto-detected built steps, let’s add those two build steps to your project instead.

You’ll start by adding a Flake8 linting step to your TeamCity project.

  1. Click Build Steps to discard the auto-detected build steps.
  2. Click Add Build Step and choose Runner type: Python to add a build step capable of building Python code.
  3. Choose Command: Flake8, as this Python project has a Flake8 dependency for linting. If your project was using Pylint for linting, you would choose Pylint.
  4. You can specify the directory you want to lint in the Script or module arguments field. Set it to “src/anewtodolist” if you are working with the Python repository from this tutorial. Or optionally, leave it empty, to lint the whole project.
  5. Optionally: Choose a different major Python version if your Project still uses 2.x.
  6. Environment Tool: This project uses Virtualenv for all dependencies it needs, such as Flake8 and PyTest. Make sure to enable Virtualenv support by selecting it as the environment tool.
  7. Click Save.

If you successfully created your build step, you will see the following dialog.

Next, let’s add a PyTest step to your project.

  1. (Optional) If you are not on the Build Steps Overview page, click Build Steps to discard the auto-detected build steps.
  2. Click Add Build Step and choose Runner type: Python to add a build step capable of building Python code.
  3. Choose Command: Pytest, as this Python project has a Pytest dependency for the test. If your project was using UnitTest for testing, you would choose UnitTest.
  4. Optionally: You can specify the directory you want to be tested in the Script or module arguments field. Or leave it empty, if your tests live under the /tests folder, which the Python runner will detect automatically.
  5. Optionally: Choose a different major Python version if your Project still uses 2.x.
  6. Environment Tool: This project uses Virtualenv for all dependencies it needs, such as Flake8 and PyTest. Make sure to enable Virtualenv support by selecting it as the environment tool.
  7. Click Save.

Step 2 – Run your first build

You can now run your first builds.

  1. Click the Run button in the top right-hand corner of the window, as shown below.
  2. Wait for the build to start and finish.

Note: If you are using TeamCity Cloud, it could take up to a couple of minutes for a build agent to become available. During this time, your build will wait in the queue until it is picked up by an available agent.

If you are using TeamCity On-Premises with local build agents, your build will start immediately.

Once your build starts, you will be redirected to the build’s overview page with the Build Log tab open, which displays real-time data related to your build.

After the build has run, you will be redirected to the build’s overview page. You can now have a look at your test results and inspections, or browse the complete build log from the build’s overview page.

Step 3 – Configuring your Python TeamCity project

Now that your Python repository is connected to TeamCity, you can continue to develop and push your code to your repository.

By default, TeamCity will poll the main branch of your VCS repository every 60 seconds for incoming changes and trigger one (combined) build for all detected commits.

Building branches

If you want to trigger a build for every change to any branch in your repository, not just the main branch, add a wildcard branch specification to your VCS Root settings. Note that VCS settings belong to the TeamCity project, not to a single build configuration. Hence, any changes you make will be applied to all build configurations that use the same VCS root.

  1. On the project’s overview page, click Edit Project. Alternatively, if you have the Build build configuration open, click Edit Configuration.
  2. Navigate to VCS Roots (Version Control Systems) and edit your VCS Root.
  3. Fill out the Branch Specification input field and click Save. If you cannot see the Branch Specification input field, click Show Advanced first.

Example branch specifications:

  • +:refs/heads/* – TeamCity will check for changes in all the branches of your projects, but it won’t check pull-requests on platforms like GitHub, as they match refs/pull/*.
  • +:* – TeamCity will check for any incoming changes on any branch.
  • Your own custom branch specification.

TeamCity will now monitor all the branches that conform to your branch specification and are pushed to your repository, checking for incoming changes, and it will run builds accordingly.

Building pull requests

If you want TeamCity to automatically build pull requests that are made against your repository, you can add the Pull Request build feature to your build configuration.

  1. Open your build configuration and click Edit Configuration.
  2. Navigate to Build Features and click Add Build Feature. If you cannot see the Build Features link, click Show More.
  3. Select Pull Requests from the dropdown and choose your repository, as well as the repository provider (GitHub, GitLab, or similar).
  4. Optionally, apply Pull Request Filtering, by author or branch name.

Note: The Pull Request build feature transparently expands the branch specification (see the previous step for more information). For example, in the case of GitHub, the pull request feature will (invisibly) add +:refs/pull/* to your branch specification.

We recommend ensuring that pull request branches are not included in your general branch specification when the pull request feature is used, because otherwise pull request-related features will not be available in TeamCity.

TeamCity will now check the external platform for pull requests and trigger a build for those matching your configuration rules.

Note: You should use this feature with caution on public repositories, as anyone could push harmful code to the repository (which you wouldn’t want to build).

Commit Status Publishers

When using the pull requests feature in combination with Azure DevOps, Bitbucket Server, GitHub, or GitLab, it also makes sense to use the Commit Status Publisher build feature. This feature will update the pull request’s status on the corresponding platform with the build results.

To set TeamCity up to report build results back to GitHub, you’ll need to follow these steps:

  1. Open your build configuration and click Edit Configuration.
  2. Navigate to Build Features and click Add Build Feature.
  3. Select Commit Status Publisher from the dropdown and choose your repository and a publisher (GitHub, GitLab, or similar).
  4. Provide an access token with sufficient rights to publish commit statuses.
  5. Click Save.

After TeamCity runs a build, you will now easily see if the changes caused a build failure right from the Pull Request tab on GitHub (green check mark).