How to Clone a Repository using HTTPS Authentication in Fedora Forge

DRAFT DOCUMENTATION: This documentation is currently in draft form and may not be fully tested and correct. Please verify all procedures before use and report any issues or inaccuracies.

Purpose

This document provides a step-by-step guide on how to clone a repository from the Fedora Forge instance using HTTPS authentication. This method is recommended as SSH cloning is currently not supported. It will also cover how to use Access Tokens for authentication, which is the secure and recommended practice for automated or repeated access.

Scope

This guide is intended for all Fedora Project contributors and users who need to clone repositories from Fedora Forge to their local machine for development, contribution, or viewing.

Prerequisites

Before you begin, ensure you have the following:

  • Git Installed: You must have Git installed on your local machine.

  • Fedora Forge Account: An active user account on the Fedora Forge instance, authenticated via Fedora Accounts (OpenIDC).

  • Access Token: For secure and convenient authentication, it is highly recommended to generate and use a Access Token instead of relying on your Fedora Account credentials directly for Git operations. See the section below on "Generating an Access Token."

Procedure: Cloning a Repository via HTTPS

Follow these steps to clone a repository using HTTPS:

1. Locate the Repository’s HTTPS URL

  1. Navigate to the repository you wish to clone on the Fedora Forge instance (e.g., https://forge.fedoraproject.org/<org>/<repo_name>;).

  2. On the repository’s main page, locate the blue "HTTPS" button (or similar clone button).

  3. Copy the provided HTTPS URL to your clipboard. It will typically look something like: https://forge.fedoraproject.org/<org>/<repo_name>.git

2. Clone the Repository Using Git

  1. Open your terminal or command prompt.

  2. Navigate to the directory where you want to clone the repository.

  3. Use the git clone command followed by the copied HTTPS URL:

    git clone https://forge.fedoraproject.org/<org>/<repo_name>.git

    Replace https://forge.fedoraproject.org/<org>/<repo_name>.git with the actual URL you copied.

  4. When you try to push changes back to this repository, you will prompted for a username and password:

    • Username: Enter your Fedora Forge username (the same one you use to log in to the web interface).

    • Password: Instead of your Fedora Account password (which is not used for Git authentication), enter your Access Token.

      Username for 'https://forge.fedoraproject.org': your_username
Password for 'https://your_username@forge.fedoraproject.org': <paste_your_access_token_here>

      When you type or paste your Access Token, it will likely not be displayed on the screen for security reasons.

  5. To avoid entering your Access Token every time you interact with the repository, you can use a Git credential helper.

    git config --global credential.helper store

    The first time you clone or push, you’ll be prompted for your username and Access Token. Git will then store it in a plain-text file (~/.git-credentials)

Generating a Access Token in Fedora Forge

Using a Access Token is the recommended way to authenticate with Git over HTTPS. Remember, you will use your Access Token for Git authentication, not your Fedora Account password.

  1. Go to https://forge.fedoraproject.org/ and log in using your Fedora Account.

  2. Click on your profile picture/icon in the top-right corner.

  3. Select "Settings" from the dropdown menu.

  4. In the left-hand navigation sidebar, click on "Applications".

  5. Under the "Access Tokens" section, click the "Generate Token" button.

  6. Token Name: Give your token a descriptive name (e.g., my-laptop-git).

  7. Token Permissions: Select the permissions you want to grant to this token. For general cloning and pushing, you will typically just need: Read and Write on Repository.

  8. Click the "Generate Token" button.

  9. Your new Access Token will be displayed. Copy this token immediately and store it securely. You will not be able to see it again once you leave this page. Treat it like a password.

Troubleshooting and Tips

  • "Authentication failed" error:

    • Double-check your username.

    • Ensure you are using the correct Access Token, not your Fedora Account password.

    • Verify the Access Token has the necessary read:repository and write:repository permissions.

    • If you’ve recently changed your Access Token, ensure your credential helper (if used) has been updated. You might need to clear cached credentials.

  • "Repository not found" error:

    • Verify the repository URL is correct and that you have access to the repository.

  • SSH Not Supported: Remember that Fedora Forge currently does not support cloning via SSH. Always use the HTTPS URL.

  • Token Security: Keep your Access Tokens secure. If you suspect a token has been compromised, revoke it immediately from your Fedora Forge "Applications" settings.

Want to help? Learn how to contribute to Fedora Docs ›