JACoB PR for Issue Integrate Linear Task Management into Application Settings

[jacob-ai-bot[bot]]

Summary:

Description

We need to create an integration with the task management tool Linear that functions similarly to our existing Jira integration. The integration will allow users to connect their Linear accounts, select specific boards, and synchronize issues between Linear and GitHub.

Requirements

1. OAuth Authentication Flow

   • Add a "Connect to Linear" button in the project settings.
   • When clicked, initiate an OAuth flow to authenticate the user with Linear.
   • Upon successful authentication, capture the accessToken and refreshToken from the callback.
   • Securely save these tokens to the database.

2. Board Selection

   • After authentication, redirect the user back to the settings page.
   • Provide an interface for the user to select the specific Linear board associated with the project.

3. Board Synchronization

   • Implement an option to "Sync Boards" in the settings.
   • When triggered, fetch new issues from the selected Linear board.
   • For each new issue, create a corresponding GitHub issue.
   • Utilize the enhanced issue function to ensure the GitHub issues are well-formatted and informative.

4. Automated Synchronization

   • Create a cron job that runs once an hour.
   • The cron job should:
     • Check for new issues posted on the connected Linear board.
     • For any new issues found, create corresponding GitHub issues using the enhanced issue function.

Expected Outcome

• Users can seamlessly connect their Linear accounts through the settings.
• Selected Linear boards are linked to the user's project in our application.
• New issues in Linear are automatically reflected as GitHub issues in the associated repository.
• The enhanced issue function ensures all created GitHub issues maintain a high standard of quality.
• The integration mirrors the functionality of the existing Jira integration for consistency.

Notes

• Ensure all tokens and sensitive information are securely stored and handled according to best practices.
• Reference the existing Jira integration codebase for implementation patterns and consistency.
• Compliance with Linear's API and usage policies is mandatory during development.
• We already have a Jira integration, please ensure that you follow the same basic patterns as that integration @jacob-ai-bot --skip-build

Plan:

Step 1: Create /src/server/db/migrations/YYYYMMDDHHMMSS_addLinearToAccountsAndProjects.ts

Task: Create migration to add Linear columns to accounts and projects tables

Instructions: Create a new migration file that adds linearAccessToken and linearRefreshToken columns to the accounts table, and adds a linearBoardId column to the projects table. Ensure that the new columns are nullable and use appropriate data types such as text for tokens and identifiers.

Exit Criteria: The migration file can be run to update the database schema without errors, adding the specified columns.

Step 2: Edit /src/server/db/tables/accounts.table.ts

Task: Add Linear columns to AccountsTable model

Instructions: In the file /src/server/db/tables/accounts.table.ts, add two new nullable text columns named linearAccessToken and linearRefreshToken to the AccountsTable class. These columns will store the Linear OAuth tokens for each user account.

Exit Criteria: The AccountsTable model includes the new columns, and the application can interact with the accounts table, including the new columns, without errors.

Step 3: Edit /src/server/db/tables/projects.table.ts

Task: Add linearBoardId to ProjectsTable model

Instructions: In the file /src/server/db/tables/projects.table.ts, add a new nullable text column named linearBoardId to the ProjectsTable class. This column will store the selected Linear board ID for each project.

Exit Criteria: The ProjectsTable model includes the new column, and the application can interact with the projects table, including the new column, without errors.

Step 4: Create /src/app/api/auth/linear/callback/route.ts

Task: Implement Linear OAuth callback route

Instructions: Create a new API route at /src/app/api/auth/linear/callback/route.ts to handle the OAuth callback from Linear. This route should extract the authorization code and state from the query parameters, validate them, and exchange the authorization code for access and refresh tokens using Linear's token endpoint. The obtained tokens should be stored in the accounts table under linearAccessToken and linearRefreshToken for the authenticated user. After storing the tokens, redirect the user to the project's settings page.

Exit Criteria: The OAuth callback route successfully exchanges the code for tokens, stores them in the database, and redirects the user to the settings page.

Step 5: Create /src/server/api/routers/linear.ts

Task: Create TRPC router for Linear integration

Instructions: Create a new TRPC router at /src/server/api/routers/linear.ts to handle Linear integration. This router should include procedures similar to the existing Jira router, such as isUserConnectedToLinear, getBoards, saveLinearBoardId, and syncBoard. These procedures will manage the connection status, fetch available Linear boards, save the selected board ID for a project, and synchronize issues from Linear.

Exit Criteria: The Linear TRPC router is created with the necessary procedures and can be used by the frontend to manage Linear integration.

Step 6: Edit /src/app/dashboard/[org]/[repo]/settings/Settings.tsx

Task: Add 'Connect to Linear' button and UI components to Settings page

Instructions: In the settings page component at /src/app/dashboard/[org]/[repo]/settings/Settings.tsx, add a 'Connect to Linear' button similar to the 'Connect to Jira' button. Implement the logic to handle Linear authentication status. After successful authentication, provide an interface for the user to select a Linear board to associate with the project. Ensure state management and UI elements follow the existing patterns used for Jira integration.

Exit Criteria: Users can connect their Linear accounts, select a Linear board, and initiate synchronization from the settings page.

Step 7: Create /src/server/utils/linear.ts

Task: Implement utility functions for Linear API interactions

Instructions: Create a new utility module at /src/server/utils/linear.ts that includes functions for interacting with the Linear API. Implement functions such as refreshLinearAccessToken, fetchLinearBoards, syncLinearBoard, and fetchNewLinearIssues. These functions should handle token refreshing, fetching available boards, synchronizing issues from Linear, and creating corresponding GitHub issues using the enhanced issue function. Follow similar patterns to the existing Jira utility functions.

Exit Criteria: The utility module provides necessary functions to interact with the Linear API and supports board synchronization.

Step 8: Edit /src/server/messaging/listener.ts

Task: Add cron job for fetching new Linear issues

Instructions: In the listener file at /src/server/messaging/listener.ts, add a new cron job that runs once an hour to fetch new Linear issues. This cron job should call a function fetchAllNewLinearIssues (implemented in the Linear utility module) that iterates over all projects connected to Linear, fetches new issues from the associated Linear boards, and creates corresponding GitHub issues using the enhanced issue function.

Exit Criteria: New Linear issues are automatically synchronized to GitHub via the cron job.

Step 9: Edit /src/types.ts

Task: Add 'Linear' to IssueBoardSource enum

Instructions: In the types file at /src/types.ts, add 'Linear' as a new value to the IssueBoardSource enum. This will be used to distinguish Linear boards in the issue boards table and other parts of the application.

Exit Criteria: The 'Linear' value is added to IssueBoardSource, and can be used in the application to identify Linear issue boards.

Step 10: Create /src/server/db/migrations/YYYYMMDDHHMMSS_addLinearToIssueSourceEnum.ts

Task: Create migration to add 'Linear' to issue_source enum

Instructions: Create a new migration file at /src/server/db/migrations/YYYYMMDDHHMMSS_addLinearToIssueSourceEnum.ts that alters the issue_source enum type in the database to include 'Linear' as a valid value. Ensure that the migration handles both the up and down cases correctly.

Exit Criteria: The migration file updates the issue_source enum in the database successfully, adding 'Linear' as a valid value.

[jacob-ai-bot[bot]]

Hello human! 👋

This PR was created by JACoB to address the issue Integrate Linear Task Management into Application Settings

Next Steps

1. Please review the PR carefully. Auto-generated code can and will contain subtle bugs and mistakes.

2. If you identify code that needs to be changed, please reject the PR with a specific reason. Be as detailed as possible in your comments. JACoB will take these comments, make changes to the code and push up changes. Please note that this process will take a few minutes.

3. Once the code looks good, approve the PR and merge the code.