YouTrack Standalone 2020.3 Help

Import from GitHub

Follow the instructions on this page to import bug reports from GitHub with a Python import script. This procedure requires the following steps:

  1. Set up your local environment.

  2. Import your issues.

Import Details

If the GitHub project contains references to entities that do not already exist in YouTrack, they are created. The user account that you use to run the import should have permission to create projects, issues, users, and possibly more. We recommend that you use an account with a System Admin role to execute the import script.

New entities are created as follows:

Entity

Description

Projects

If the project that is referenced in the import source does not already exist, a new project is created.

  • The project name and ID are assigned based on the values from the GitHub project.

  • The user who executes the import script is set as the project owner.

Users

Several issue attributes like reporterName and Assignee store references to user accounts. The values in the import are checked against existing user accounts by email. For each new value that does not match the email for an existing user, a new user account is created.

  • The email address is also used as the login for the imported user account.

  • All new user accounts are assigned randomly-generated passwords. To log in to YouTrack, imported users must click the Reset password link on the login page and create a new password.

Custom Fields

If the import data contains a field that does not exist in YouTrack, the custom field is created and added to the target project.

  • The field name and type are set according to the definitions in the import script.

  • The properties for the custom field are set as follows: autoAttached=true, isPrivate=false, defaultVisibility=false.

Field Values

If the source file contains new values for an existing field, they are added to the current set of values.

Set Up Your Environment

Import to YouTrack is supported by Python import scripts. These scripts are built on top of the YouTrack REST API. You won't actually need to do any programming in Python, but you do need to install Python and the package that contains the import scripts.

To set up your environment:

  1. Download and install Python. The import scripts are compatible with Python 2.7+. Python 3 releases are not supported. You can choose whichever installation directory you prefer.

    The latest versions of macOS, CentOS, Red Hat Enterprise Linux (RHEL), and Ubuntu come with Python 2.7 out of the box. If you're working with any of these operating systems, continue with the next step.

  2. Open the command-line interface that is supported by your operating system.

  3. Verify that your Python installation includes the virtualenv package by running the following command:

    pip install virtualenv

    This ensures that you are able to execute commands in YouTrack import scripts without encountering a Command not found message.

  4. Install the package that contains the import scripts with the following command:

    pip install youtrack-scripts

    • The import scripts are installed in your local environment.

    • The youtrack package that contains the Python client library for the YouTrack REST API is installed automatically as a dependency.

    If you prefer not to install the packages globally, you can install them for your user account only with the command:

    pip install --user youtrack-scripts

Import Your Data

The last step is to run the command that imports your data from GitHub.

To import your data:

  1. Open the command-line interface that is supported by your operating system.

  2. If necessary, change the current directory to the installation directory for Python. For example (Windows):

    cd C:\Python27

  3. Enter the following command:

    github2youtrack -t token -u login -p password target_url github_user github_password github_repo

    Replace the command-line parameters with values as described here:

    Parameter

    Description

    token

    When used with the -t option, a permanent token that is used to authenticate your administrator account in YouTrack. This is the preferred method of authentication. If you use this option, skip the -u and -p options. To learn how to generate a permanent token, see Create a Permanent Token.

    Alternatively, you can use the -T option and specify the full path and filename for a file that contains a permanent token.

    login

    When used with the -u option, the login for a YouTrack administrator account. You must also specify a value for the -p option.

    password

    When used with the -p option, the password for the YouTrack administrator account.

    target_url

    The base URL of the target YouTrack server. For YouTrack InCloud instances, your base URL includes the trailing /youtrack. For example: https://company.myjetbrains.com/youtrack

    github_user

    The username of the account that you use to log in to GitHub.

    github_password

    The password for the account that you use to log in to GitHub.

    github_repo

    The name of the GitHub repository that you want to import issues from. If the owner of the repository is not the same user that is specified for the github_user parameter, reference the repository with the format repo_owner/repo_name.

    • The command executes the Python import script.

    • If successful, the following line is printed in the command-line interface for each issue:

      Issue [ <issue ID> ] imported successfully

  4. Check the project or projects that you imported issues into and verify that the data is presented properly. If you are not satisfied with the results and want to re-import the data:

    • Delete all of the issues that were created during import. If you imported issues into a new project, simply delete the project.

    • Run the import script again.

Default Mapping

The import script maps data from issues in GitHub to issue attributes in YouTrack. For custom fields, the following mapping is applied:

GitHub

YouTrack

Project Name

project_name

Project ID

project_id

Summary

summary

State

State

ID

numberInProject

Created

created

Updated

updated

Resolved

resolved

Assignee

Assignee

Description

description

Labels

Labels

Author

reporterName

Milestone

Fix versions
Custom field types are defined as follows:

Field

Type

State

state[1]

Assignee

user[1]

Labels

enum[*]

Fix versions

version[*]

Type

enum[1]

Troubleshooting

If you encounter any errors when you run the import script, see if any of the following conditions apply.

Condition

Error for [/user/login]: 302: Moved Temporarily

Cause

The value that you used for the target_url parameter is incorrect. The most common mistake is to enter the base URL for a YouTrack instance without /youtrack at the end of the URL.

Solution

Change the value of the target_url parameter and run the import the script again. Use the value that is shown as the Base URL setting for your YouTrack service.

  1. For YouTrack Standalone, copy the value from the Base URL setting on the Global Settings page.

  2. For YouTrack InCloud, copy the value from the Base URL setting on the Domain Settings page.

Condition

Error for [<resource>]: 403: Forbidden: You have no permissions for <resource>

Cause

The user account that you used to run the import script does not have permission to read or update the target resource. The resource URL indicates which entity is not accessible to the user.

Solution

Run the import script with a user account that has sufficient permissions to update the target resource.

Last modified: 28 October 2020
Import from FogBugzImport from Mantis Bug Tracker