More descriptive error messaging when migrating from Azure DevOps

[atiterlea]

Issue

We've run into several errors when attempting to transform our Azure DevOps pipelines into GitHub Actions workflows. Some of these failures are caused by authentication errors, others are caused by as yet unknown errors buried deep within the utility. While the generated log files provide a bit more information as to the source, their content is insufficient to help us troubleshoot further. The CLI output simply reports: "There was an error extracting the Azure DevOps pipeline".

Attempts at Resolution

All we have to go on are the log files being written out by the CLI, but they don't capture everything that went wrong with the migration from ADO, or how to resolve it. For example, the following error tells us that the URL provided is incorrect, but we don't know why it's not able to reach out to a GitHub URL or how to remediate it:

There was an error extracting the Azure DevOps pipeline (https://dev.azure.com/<Organization>/<Repository>/_build?definitionId=<#>)
Message: Unable to parse Azure DevOps project URL. Ensure it is in the format of https://dev.azure.com/:organization/:project_name/git/:repository_name
Azure DevOps URL provided: https://github.com/<Organization>/<Repository>.git

Is this simply a limitation of the importer (i.e. the repo must be defined in ADO) or a misconfiguration on our part? There are other 404 errors that provide even less information:

Resource not found
(GET 404) Not Found: https://api.github.com/repos/<owner>/<repo>/contents/.pipelines/<pipeline>.yml?ref=refs/heads/master
Message: Not Found

The above error doesn't give us any actionable information so we're left to fumble in the dark; the resource exists, but the importer can't seem to find it.

Possible Fixes?

Is there any way to get more detailed information on the search paths, or to print out a stack trace of the error cases the importer encounters? Since the importer pulls down and executes a Docker container with the Valet program, can we bubble up those Ruby errors to the CLI or increase the logging level so that we can step through what the program is doing?

[simonsanchez]

Hi @atiterlea, thanks for opening this issue and for your feedback! In terms of more detailed errors, I will confer with the team on how we can improve surfacing this information. In the meantime, can you share the following information please?

• What version of the CLI are you using? You can find this by running gh actions-importer version
• What version of Docker are you using? You can find this by running docker version
• What OS and version are you using?
• The command(s) you ran that resulted in the errors you shared above.

[mitchell-liatrio]

Hi @simonsanchez, I have the information requested above.

gh actions-importer version

• gh version 2.29.0 (2023-05-10)
• gh actions-importer github/gh-actions-importer v1.2.3
• actions-importer/cli:latest v1.3.19810

docker version

• Client:
• Version: 24.0.2-rd
• API version: 1.43
• Go version: go1.20.4
• Git commit: e63f5fa
• Built: Fri May 26 16:40:56 2023
• OS/Arch: darwin/arm64
• Context: desktop-linux

OS/Version:

• MacOS Ventura Version 13.4.1 (c)

Command:

• audit

[simonsanchez]

Is this simply a limitation of the importer (i.e. the repo must be defined in ADO) or a misconfiguration on our part?

The tool does support resources hosted on GitHub when using templates. Sample config

# Repo: Contoso/LinuxProduct
# File: azure-pipelines.yml
resources:
  repositories:
    - repository: templates
      type: github
      name: Contoso/BuildTemplates

jobs:
- template: common.yml@templates  # Template reference

As for the 404 mentioned

the resource exists, but the importer can't seem to find it.

Ensure the access token has the required scopes. From the GitHub docs

Typically, we send a 404 error when your client isn't properly authenticated. You might expect to see a 403 Forbidden in these cases. However, since we don't want to provide any information about private repositories, the API returns a 404 error instead.
To troubleshoot, ensure you're authenticating correctly, your OAuth access token has the required scopes, third-party application restrictions are not blocking access, and that the token has not expired or been revoked.

We will extend the messaging to be more clear in these cases.

[simonsanchez]

Hi all, the error messaging has been extended in the latest release. Please update to the latest release by running gh actions-importer update.

Were you able to rule out whether an invalid access token was the root cause of the 404?