How to Fix “fatal: unable to access ‘xxx’: The requested URL returned error: 403” in CI/CD

Nitin

3 months ago

If you’re running a CI/CD pipeline and hit the error “fatal: unable to access ‘xxx’: The requested URL returned error: 403,” it can feel like you’ve slammed into a brick wall. Don’t worry—you’re not the first to see this, and it’s totally fixable! Imagine you’re trying to get into a private club, but the bouncer says, “Nope, you’re not on the list.” That’s basically what’s happening here—your pipeline is trying to access a Git repository, but the server’s saying “access denied” with a 403 error. In this guide, I’ll break it down for you in simple terms, explain why it happens, and show you step-by-step how to solve it. Let’s get your pipeline running smoothly again!

What Does This Error Mean?

First, let’s decode the message: “fatal: unable to access ‘xxx’: The requested URL returned error: 403.” Here’s what each part means:

fatal: This is Git’s way of saying, “Yikes, this is a big problem—I’m stopping everything.”
unable to access ‘xxx’: Git tried to reach a repository (the ‘xxx’ is the URL it’s trying to hit), but it couldn’t get in.
The requested URL returned error: 403: The server responded with a 403 Forbidden error, which means “You’re not allowed here.”

In a CI/CD setup—like GitLab, GitHub Actions, or Jenkins—this usually happens when your pipeline tries to clone, pull, or push to a Git repository but doesn’t have the right permissions. Think of it like needing a VIP pass to get backstage, but your pass is missing or expired.

Why Does This Happen in CI/CD?

There are a few common reasons your CI/CD pipeline might hit this 403 wall. Here’s the rundown:

Wrong or Missing Credentials: Your pipeline needs a username, password, or token to access the repo, and it’s either blank or incorrect.
Expired Access Token: If you’re using a Personal Access Token (PAT) or similar, it might have timed out or been revoked.
Permission Issues: The account or token you’re using doesn’t have the right to read or write to the repository.
Bad URL: The repository URL in your pipeline config might be mistyped or pointing to the wrong place.
Private Repository: If the repo is private, your pipeline needs explicit permission to access it—public access won’t cut it.
CI/CD Token Misconfiguration: In tools like GitLab, the built-in CI token might not be set up correctly for the job.

For example, if you’re using GitLab with a runner and see this in your logs:

Fetching changes with git depth set to 20...
fatal: unable to access 'http://gitlab.xxx.com/dev/project.git/': The requested URL returned error: 403
ERROR: Job failed: exit code 1

It’s a sign that your pipeline couldn’t authenticate properly. Let’s fix it!

How to Fix the 403 Error in CI/CD

Let’s tackle this step-by-step. These solutions work across platforms like GitHub Actions, GitLab CI/CD, Jenkins, and more. Try them in order until your pipeline’s back on track.

1. Check Your Repository URL

First things first—make sure the URL in your CI/CD config is correct. It’s like double-checking the address before you head out.

Where to Look: In your pipeline config file (e.g., .gitlab-ci.yml for GitLab, .github/workflows/main.yml for GitHub Actions).
What to Check: Look for the git clone, git pull, or git push command and the URL it’s using. For example:

  git clone http://gitlab.xxx.com/dev/project.git

Fix It: If it’s wrong (e.g., a typo or old URL), update it to match your repo’s actual address. You can find the right URL on your Git hosting site (GitHub, GitLab, Bitbucket, etc.) under the repo’s “Clone” or “HTTPS” option.

Once updated, rerun the pipeline. If it still fails, move on.

2. Verify Authentication Credentials

Most 403 errors boil down to authentication—your pipeline isn’t proving it’s allowed in. Here’s how to fix that:

For HTTPS: If your repo uses HTTPS (e.g., https://github.com/username/repo.git), you need a username and password or a token.
GitHub: Use a Personal Access Token (PAT) instead of a password (GitHub stopped accepting passwords for Git over HTTPS in 2021).
- Go to GitHub > Settings > Developer Settings > Personal Access Tokens > Tokens (classic) > Generate new token.
- Give it repo scope (full control of private repos) and save it.
GitLab: Use a PAT or the built-in CI_JOB_TOKEN (more on that later).
Add Credentials:
In your pipeline, embed the token in the URL like this:
git clone https://<username>:<token>@github.com/username/repo.git
Better Option: Store it as a secret variable (safer than hardcoding):
- GitHub Actions: Go to Repo > Settings > Secrets and Variables > Actions > New repository secret (e.g., GIT_TOKEN).
- GitLab: Go to Settings > CI/CD > Variables > Add Variable (e.g., GIT_TOKEN, mark it as masked).
- Use it in your config:
# .gitlab-ci.yml example before_script: - git clone https://$GIT_TOKEN@gitlab.com/username/repo.git
Test It: Rerun the pipeline. If it works, you’re golden!

3. Use SSH Instead of HTTPS

If HTTPS keeps failing, switch to SSH—it’s often more reliable for CI/CD because it uses key-based authentication.

Step 1: Generate an SSH Key (if you don’t have one):
On your local machine or CI server, run:
ssh-keygen -t ed25519 -C "your-email@example.com"
Press Enter to accept defaults, then copy the public key (~/.ssh/id_ed25519.pub).
Step 2: Add the Key to Your Git Host:
GitHub: Settings > SSH and GPG Keys > New SSH Key > Paste the public key.
GitLab: Settings > SSH Keys > Paste the public key.
Step 3: Store the Private Key in CI/CD:
Copy the private key (~/.ssh/id_ed25519) and add it as a secret:
- GitHub: Repo > Settings > Secrets > New secret (e.g., SSH_PRIVATE_KEY).
- GitLab: Settings > CI/CD > Variables > Add Variable (e.g., SSH_PRIVATE_KEY, mark it as protected).
Step 4: Update Your Pipeline Config:
Example for GitLab (.gitlab-ci.yml):
“`yaml
before_script:
- mkdir -p ~/.ssh
- echo “$SSH_PRIVATE_KEY” > ~/.ssh/id_ed25519
- chmod 600 ~/.ssh/id_ed25519
- ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
- git clone git@gitlab.com:username/repo.git
  “`
Example for GitHub Actions: steps: - name: Setup SSH run: | mkdir -p ~/.ssh echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_ed25519 chmod 600 ~/.ssh/id_ed25519 ssh-keyscan github.com >> ~/.ssh/known_hosts - name: Clone Repo run: git clone git@github.com:username/repo.git env: SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
Run It: If SSH works, you’ve bypassed the HTTPS 403 issue!

4. Check Repository Permissions

Sometimes the account or token you’re using doesn’t have permission to access the repo—especially if it’s private.

GitHub:
Go to Repo > Settings > Collaborators & Teams.
Ensure the user or token has “Write” access (for pushing) or at least “Read” (for cloning/pulling).
For Actions, check that the GITHUB_TOKEN has the right scopes (default is read-only unless you tweak workflows).
GitLab:
Go to Project > Members.
Confirm the user or runner has at least “Developer” role (for push/pull).
If using a runner, ensure it’s registered and linked to the project (Settings > CI/CD > Runners).
Fix It: Add the user or update token permissions, then retry the pipeline.

5. Fix CI/CD Token Issues (GitLab-Specific)

In GitLab, the CI_JOB_TOKEN is often used to authenticate pipelines. If it’s failing with a 403, here’s why and how to fix it:

Why It Fails: The token might not have access to the repo (e.g., submodules or cross-project access).
Check Logs: Look for gitlab-ci-token in the failing URL, like:

  fatal: unable to access 'https://gitlab-ci-token:[MASKED]@gitlab.com/dev/project.git/': The requested URL returned error: 403

Fix It:
Use a PAT instead (see Step 2).
Or, ensure the runner’s token has access:
- Go to Settings > CI/CD > Runners > Check the runner’s status.
- Re-register if needed:
  gitlab-runner register --url https://gitlab.com/ --registration-token <your-token>

6. Debug with Manual Testing

If you’re still stuck, test the repo access manually to pinpoint the issue.

On Your Machine:
Run: git clone https://username:token@gitlab.com/dev/project.git
If it fails with 403, your credentials or URL are off—fix them.
In CI/CD:
Add a debug step to your pipeline:
yaml # .gitlab-ci.yml debug: script: - git config --global credential.helper store - echo "https://$GIT_TOKEN@gitlab.com" > ~/.git-credentials - git clone https://gitlab.com/dev/project.git || echo "Clone failed!"
Check the output for clues.

Example: Fixing a GitLab CI/CD Pipeline

Here’s a real-world fix for a .gitlab-ci.yml file:

Before (Failing):

stages:
  - build
build_job:
  stage: build
  script:
    - git clone http://gitlab.xxx.com/dev/project.git

After (Working with SSH):

stages:
  - build
build_job:
  stage: build
  before_script:
    - mkdir -p ~/.ssh
    - echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_ed25519
    - chmod 600 ~/.ssh/id_ed25519
    - ssh-keyscan gitlab.xxx.com >> ~/.ssh/known_hosts
  script:
    - git clone git@gitlab.xxx.com:dev/project.git
  variables:
    SSH_PRIVATE_KEY: $SSH_PRIVATE_KEY

After (Working with HTTPS):

stages:
  - build
build_job:
  stage: build
  script:
    - git clone https://$GIT_TOKEN@gitlab.xxx.com/dev/project.git
  variables:
    GIT_TOKEN: $GIT_TOKEN

Add GIT_TOKEN or SSH_PRIVATE_KEY as a secret in Settings > CI/CD > Variables, and you’re set!

Tips to Prevent This in the Future

Use SSH: It’s more secure and less prone to 403 errors than HTTPS.
Rotate Tokens: Set reminders to refresh PATs before they expire.
Test Locally First: Clone or push to the repo manually before setting up CI/CD.
Document Access: Keep track of who or what has repo permissions.

Still Not Working?

If you’ve tried everything and the 403 persists:

Check your Git host’s status page (e.g., GitHub Status, GitLab Status) for outages.
Post your pipeline logs on Stack Overflow or your CI/CD tool’s forum—include the full error and what you’ve tried.
Contact your repo admin to double-check permissions.

Summary: You’ve Conquered the 403!

That “fatal: unable to access ‘xxx’: The requested URL returned error: 403” error might’ve slowed you down, but now you’ve got the tools to fix it. Whether it’s tweaking credentials, switching to SSH, or sorting out permissions, you’re ready to get your CI/CD pipeline humming again. It’s like figuring out the secret handshake to get into that exclusive club—once you’ve got it, you’re in! What’s your next project? Let me know how it goes in the comments—I’m rooting for you!

Table of Contents