GitHub Actions Integration
Follow the instructions on this page to configure integration with GitHub Actions.
The integration with GitHub Actions becomes possible when you've established a connection between YouTrack and a VCS repository that is hosted on github.com. To learn how to integrate YouTrack with GitHub, see GitHub Integration.
The integration between YouTrack and GitHub Actions enables useful features in both applications:
Pull pipeline IDs from connected projects in GitHub Actions and automatically update the values in custom fields that store build numbers for resolved issues.
Apply commands to issues in YouTrack when GitHub Actions runs a job that contains the commit referencing the issue.
Before you start, verify that the authentication token that you used for the GitHub integration is valid. If you're adding a GitHub Actions integration to a GitHub integration set up some time ago, the token may expire soon. You can check the expiration date of the token and generate a new token on the Personal access tokens page in GitHub.
To start using features of the integration with GitHub Actions, define one or several integration jobs in YouTrack.
Each integration job must match an existing job in GitHub Actions by name. You can define integration jobs in the settings of an existing GitHub integration.
From the
Administration menu in YouTrack, select Integrations > VCS Integrations.
Select the target GitHub integration from the list of configured integrations.
In the sidebar, scroll down to the GitHub Actions section.
Click the New integration button.
Add a name for the integration job. The job name will be matched with the job name in the GitHub Actions configuration file
.yml
. If a job in GitHub Actions doesn't match any integration job in YouTrack, it will not be processed by YouTrack.note
An integration in YouTrack is triggered when a corresponding job in GitHub Actions finishes successfully.
When triggered, the integration processes all changes made in the same branch between the last processed job in GitHub Actions and the current one.
Note that if you run a job in one of the old pipelines in GitHub Actions, the integration will not process the changes backward.
Click the Add button.
You've added and enabled a new integration job.
Define the settings for the new job.
To learn more about these settings, see Integration Settings.
Click the Save button.
You've defined a new integration job for the GitHub Actions integration.
The following settings are available for an integration job.
Option | Description |
---|---|
Pull data from finished job | Determines if the integration listens for only successfully finished jobs, all jobs unless the job was canceled, or considers all every job. |
Add GitHub Action ID to the set of values in a custom field | Determines which custom field is populated with build numbers in the integrated YouTrack project. The selection is restricted to custom fields that store a As GitHub Actions operate with pipelines instead of builds, YouTrack stores pipeline IDs instead of build numbers as custom field values. The value for the selected field is set automatically in any issue updated by the integration. The settings in the Select which issues to update section of the integration determine which issues are assigned build numbers. The following option is available:
|
Select which issues to update | The options in this section determine which issues are assigned build numbers by the integration. The following options are available:
If both options are enabled, build numbers are automatically assigned to issues that meet either of these two conditions.
|
Update selected issues | Determines whether the integration applies changes to the selected issues in addition to the automatic build number assignment. When the Apply a command option is enabled, you can enter a predefined command applied to all issues that are assigned build numbers. Use the With this command, all issues that are processed by YouTrack are assigned to the Testing subsystem and the Test in build field is set to the build number. |
When you've created an integration job, the following actions are available for this job:
Action | Description |
---|---|
Edit | Opens the Edit Job Name dialog where you can edit the name of the integration job. |
Remove | Removes the integration job from YouTrack. All changes made by the integration remain in place. |
You can use placeholders in the Query and Command settings. These placeholders reference attributes that are stored for jobs and pipelines in GitHub Actions. The placeholder is replaced with the corresponding value in GitHub when the job is processed by YouTrack. The following placeholders are available:
Placeholder | Description |
---|---|
${build.time} | The date and time of the job that is processed by YouTrack. |
${prev.build.time} | The date and time of the job prior to the one that is processed by YouTrack. |
${build} | The ID of the pipeline with the job that is processed by YouTrack. |
The vcs.log file for your YouTrack site contains records of events related to GitHub and other VCS integrations. Check this file for information about processed issues, applied settings, errors, and problems.
If you need any help checking this file, contact YouTrack support.
If you experience problems setting up the GitHub Actions integration, see if any of the following conditions apply.
Condition - The integration isn't assigning job IDs to YouTrack issues.
Cause | Solution |
---|---|
The webhook that connects to GitHub isn't configured to check for relevant activity or the user account used to establish the connection has insufficient permissions. | Select the VCS integration in the list and click the Disable button. Once the integration has been disabled, click the Enable button. This operation has two outcomes:
|
Condition — The vcs.log file reports an error similar to the following:
24/03/22 11:29:42,465 INFO [@csJobProcessor0] [service ] [git_hosting_integration_1481972073@null] [GitHub Integration NP%3C-anita.freeman/development (branch spec: )]:
499957071 -> related issue: NP-164 not matched query 'State: Fixed State: Verified resolved date: 2022-03-24T08:29:42 .. 2022-03-24T08:29:42'
Cause | Solution |
---|---|
An issue mentioned in a commit message doesn't match the query in the integration settings. | Adjust the query in the settings or make the related issue match the existing query. |
Condition — The vcs.log file reports an error similar to the following:
24/03/22 11:34:50,966 INFO [@csJobProcessor0] [service ] [git_hosting_integration_1481972073@null] [GitHub Integration NP%3C-anita.freeman/development (branch spec: )]:
no suitable build processor for: test
Cause | Solution |
---|---|
The name of the job in the YAML configuration file in GitHub doesn't match any job in the integration settings. | Change the job name in the integration settings to match the name of the job in GitHub Actions. Alternatively, add a new integration job with the name matching a GitHub Actions job. |
Thanks for your feedback!