Migrate from Project Handbook to Asana

Project Handbook pages are static HTML and markdown with no structured record fields. They do not export as a data set. If the customer's goal is to reproduce handbook content in Asana, we document the page hierarchy and section headings as a written content map for manual task creation or Asana custom form setup. This is not an automated record migration — it is a content inventory delivered to the customer's admin for Asana project and task structuring.

The handbook's markdown section headers map to Asana Sections within a Project. We extract the heading hierarchy during discovery (scraping the static site structure) and deliver it as a Section ordering map for the customer's Asana admin to reproduce in the Asana project layout. This is a documentation artifact, not an automated load.

Hyperlinks embedded in handbook pages (pointing to GNOME wiki pages, GitLab issues, or external resources) map to Asana task hyperlinks or external references. We inventory all external links during discovery and deliver them as a link map, but Asana does not have a native external-link-library object, so links are either attached to relevant tasks or documented for the admin to add manually.

Project Handbook has no user management, no authentication layer, and no contributor records. There are no user objects to migrate. We configure Asana user provisioning separately: the customer supplies the list of team members who need Asana access, and we map those to Asana Workspaces and Teams with appropriate role assignments (Member, Guest, Admin). User provisioning is out-of-scope for data migration and is handled as a separate setup task.

Project Handbook contains no file attachment storage. Linked assets (images, PDFs) are external URLs hosted elsewhere. There are no attachment records to migrate. If the customer's team has assets in GNOME infrastructure (GitLab, wiki, or file storage), we can map those as Asana attachments linked to the relevant task records if the assets are identified during discovery.

Project Handbook has no structured field schema. Custom field migration does not apply. If the real source is GitLab and the customer uses GitLab Labels with structured naming conventions (e.g., priority::high, type::bug), we map those to Asana custom fields during the GitLab-to-Asana migration scope.

Project Handbook has no comment system. There are no engagement records to migrate. If the real source is GitLab, GitLab Issue comments map to Asana Stories on the corresponding task. Story text, author, and timestamp migrate directly via the Asana Stories API endpoint.

Project Handbook uses in-browser Lunr.js search scoped to the live session with no export mechanism, and markdown category tags are not structured data objects. There are no search or tag records to migrate. If the customer is migrating from GitLab, Labels on GitLab issues map to Asana Tags using the label name as the tag name, with color preservation where GitLab label colors are available via API.

During discovery, if the customer confirms the actual source is GitLab (gitlab.gnome.org or self-hosted), GitLab Groups and Projects map to Asana Portfolios or top-level Projects. A GitLab Group containing multiple Projects maps to an Asana Portfolio; a single GitLab Project maps to an Asana Project with its Issues mapped to Tasks within that Project.

GitLab Milestones map to Asana Project sections or groupings within the project timeline. We preserve milestone title, description, start date, and due date by mapping them to Asana section names and custom date fields on the milestone-associated tasks. Milestone status (active, closed, upcoming) is preserved as a custom field on each task.

GitLab Issues map directly to Asana Tasks. Issue title maps to Task name, issue description (markdown) maps to task description, issue Assignee maps to Task assignee, and issue Due Date maps to Task due date. Labels on the GitLab issue map to Asana Tags (with color) and optionally to custom field values if custom field types are configured in the Asana destination workspace.

GitLab Labels (stored on Issues, Merge Requests, and at the Project level) map to Asana Tags. Label name maps to Tag name, and label color maps to Tag color where the GitLab API exposes color data. Labels used for categorization without a direct Asana custom field equivalent are stored as tags. The customer determines during scoping which label categories require custom field treatment versus tag treatment.

GitLab Merge Requests have no direct Asana equivalent. We map MRs to Tasks with a custom MR reference field (text field containing the MR URL and MR number) and optionally link the MR task to the related Issue task using Asana task dependencies or a custom lookup field. The MR status (open, merged, closed) is tracked as a task field update.

GitLab users with access to the source Groups and Projects map to Asana Users by email address. We resolve GitLab username to Asana user by matching email on the Asana workspace user list. Any GitLab user without an Asana account is held in a user reconciliation queue for the customer admin to provision before record import. Owner and assignee references on Issues resolve to Asana user IDs at migration time.

GitLab Issue and Merge Request attachments stored in GitLab's file store (uploads) are referenced by URL. We map these as external links on the corresponding Asana task attachments array using the GitLab URL as the external link target. For attachments stored in connected cloud storage (S3, GCS), we map to Asana external file attachments linked to the task.