Add docs on replacing SSH repository URLs with HTTPS URLs

[whyscream]

This PR documents a clean solution for the configuration issue stated in #10167.

This documents:

• How to configure the (fallback) git client to use an alternative URL for a git repo listed in pyproject.toml or poetry.lock
• How to set up credentials for such a URL
• A common pitfall when configuring all this

Resolves: #10167

Summary by Sourcery

Document how to configure Git to replace SSH repository URLs with HTTPS URLs that include credentials and clarify matching URLs between pyproject.toml and poetry.lock

Documentation:

• Add a "Credentials for SSH repositories" section explaining how to set up Git url.insteadOf to use HTTPS with embedded credentials
• Include a note highlighting the difference between repository URLs in pyproject.toml and poetry.lock and the need to match the lock file URL when configuring Git

[sourcery-ai]

Reviewer's Guide

This PR updates the dependency-specification guide by adding a new “Credentials for SSH repositories" section that shows how to configure Git’s insteadOf rule to swap SSH URLs for HTTPS URLs with embedded CI tokens, and includes a note (with tabbed examples) highlighting the URL mismatch pitfall between pyproject.toml and poetry.lock.

Flow diagram for replacing SSH URLs with HTTPS URLs using Git insteadOf

flowchart TD
    A[Dependency in pyproject.toml uses SSH URL] --> B[User configures git insteadOf rule to map SSH URL to HTTPS URL with CI token]
    B --> C[User runs 'poetry lock']
    C --> D[poetry.lock contains SSH URL format]
    D --> E[Git uses insteadOf rule to access repository via HTTPS with CI token]
    E --> F[Dependency is installed without SSH keys]

Loading

File-Level Changes

Change	Details	Files
Added a new section outlining how to configure the git client to replace SSH URLs with HTTPS URLs including credentials	Introduced a “Credentials for SSH repositories” header and explanatory text Provided a git config --global url.insteadOf example embedding CI_JOB_TOKEN Added a usage example invoking ‘poetry lock’ to apply the new config	docs/dependency-specification.md
Documented the URL mismatch pitfall between pyproject.toml and poetry.lock	Inserted a note explaining that the insteadOf rule must match the URL in poetry.lock rather than pyproject.toml Included tabbed TOML examples to contrast project and tool.poetry entries	docs/dependency-specification.md

Possibly linked issues

• Git dependency install with insteadOf URL fails with poetry>2 #10167: The PR documents how to configure git url.insteadOf to use HTTPS for dependencies, addressing the failure described in the issue.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey @whyscream - I've reviewed your changes - here's some feedback:

• Consider noting that users can scope the URL replacement to the current repository by using git config --local instead of --global.
• It might be helpful to warn about the security risk of embedding credentials in plaintext within the git config and suggest alternatives like environment variables or .netrc.
• Clarify that the insteadOf URL must match the exact URL format (including ssh:// vs shorthand [email protected]:owner/repo.git) as it appears in the poetry.lock file.

Prompt for AI Agents

Please address the comments from this code review:
## Overall Comments
- Consider noting that users can scope the URL replacement to the current repository by using git config --local instead of --global.
- It might be helpful to warn about the security risk of embedding credentials in plaintext within the git config and suggest alternatives like environment variables or .netrc.
- Clarify that the insteadOf URL must match the exact URL format (including ssh:// vs shorthand [email protected]:owner/repo.git) as it appears in the poetry.lock file.

## Individual Comments

### Comment 1
<location> `docs/dependency-specification.md:409` </location>
<code_context>
+This will replace the SSH URL with the HTTPS URL that includes the credentials, allowing Poetry to access the repository without needing SSH keys.
+
+{{% note %}}
+Be aware that there is a difference between the URL used in the `pyproject.toml` file and the URL in the `poetry.lock` file. For example, if you have a dependency in you pyproject.toml file like this:
+
+{{< tabs tabTotal="2" tabID1="git-ssh-credentials-project" tabID2="git-ssh-credentials-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}
</code_context>

<issue_to_address>
Typo: 'you pyproject.toml file' should be 'your pyproject.toml file'.

Please change 'you pyproject.toml file' to 'your pyproject.toml file'.
</issue_to_address>

<suggested_fix>
<<<<<<< SEARCH
Be aware that there is a difference between the URL used in the `pyproject.toml` file and the URL in the `poetry.lock` file. For example, if you have a dependency in you pyproject.toml file like this:
=======
Be aware that there is a difference between the URL used in the `pyproject.toml` file and the URL in the `poetry.lock` file. For example, if you have a dependency in your pyproject.toml file like this:
>>>>>>> REPLACE

</suggested_fix>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}