Gitea Actions: Fix Download Issues With 'self' URL

Hey everyone! 👋 If you're running Gitea and hitting a snag with your Actions not downloading when DEFAULT_ACTIONS_URL is set to "self", you're in the right place. This guide dives deep into the problem, explores the root causes, and offers potential solutions to get your workflows up and running smoothly. Let's get started!

The Core Problem: Actions Not Downloading 😩

The heart of the issue lies in a common configuration scenario in Gitea. Specifically, when you've configured DEFAULT_ACTIONS_URL to "self", aiming to leverage your self-hosted Gitea instance for action downloads, the system sometimes fails to fetch those critical components. This often manifests as error messages in your runner logs, indicating that the actions can't be found at the expected URI, like http://gitea-service/api/v1/repos/actions/checkout/archive/v4.tar.gz.

Understanding the Symptoms

The symptoms are pretty clear-cut: your workflows get stuck because they can't download the necessary actions. You'll typically see errors in the gitea-act-runner logs, such as ActionNotFoundException, pointing to a failed download attempt. Simultaneously, Gitea's logs might show 404 Not Found errors when the runner tries to access the action archives. This mismatch suggests a breakdown in how the runner is resolving and accessing the action files within your Gitea instance. It's like the runner is looking for a file that isn't where it expects it to be, or perhaps doesn't exist.

Diving into the Error Messages

Let's break down some of the key error messages. The ActionNotFoundException is a red flag, indicating the runner couldn't locate the action at the specified URL. The log entries highlight that the runner is attempting to download the action from a URL that points back to your Gitea instance, which is precisely what you want when using the "self" setting. However, the subsequent 404 Not Found error from Gitea reveals that the server isn't serving the requested archive. This is the crucial point to understand: The runner is asking, but Gitea isn't answering with the action files.

Steps to Reproduce the Issue 🛠️

Reproducing this problem is straightforward, following the setup steps will help you confirm if the issue affects your instance too. Follow these steps to replicate the problem and observe the download failure.

Configuration is key

1. Configure DEFAULT_ACTIONS_URL: In your Gitea configuration, make sure DEFAULT_ACTIONS_URL is set to "self". This is the core setup that triggers the problem.
2. Trigger a Workflow: Initiate a workflow that utilizes GitHub Actions. This will prompt the runner to attempt downloading the specified actions.
3. Observe the Errors: Review the logs from both the gitea-act-runner and your Gitea instance. Look for errors related to action downloads, like the ActionNotFoundException or 404 Not Found errors.

Detailed Setup

By following these steps, you'll set the stage for the action download failures. Remember, the configuration of DEFAULT_ACTIONS_URL is critical, as it dictates where the runner looks for its actions. If this setting isn't correct, your workflows won't run as expected. Make sure your Gitea and runner setups are correctly configured for self-hosting. This ensures that the runner is correctly pointed towards your Gitea instance for its action downloads.

Expected vs. Actual Behavior 🤔

The discrepancy between what you expect and what you actually see is crucial for pinpointing the issue. Understanding this contrast can help you determine if your setup is incorrect.

What You Expect

Ideally, when DEFAULT_ACTIONS_URL is set to "self", your workflows should seamlessly download the actions from your Gitea instance. The runner should successfully retrieve the necessary files, allowing your workflows to execute without any hitches. Think of it as a smooth transfer, where the runner gets everything it needs from the repository it's set up to use.

The Reality of the Situation

Unfortunately, the actual behavior often deviates from this ideal. Instead of a successful download, the runner encounters errors, and your workflows fail to execute. This problem typically stems from the inability of the runner to find or access the required action files within your self-hosted Gitea instance. The system acts as if there is a roadblock in the transfer process, preventing the actions from reaching the runner.

Deep Dive into the Error Logs 🔍

Let's break down the error logs to get a clearer picture of what's happening under the hood. The logs contain valuable clues about where the process is breaking down, making it possible to identify the precise point of failure.

Gitea-Act-Runner Logs

These logs are your primary source of information on the runner's perspective. The key here is to find the exceptions and errors that provide direct insights into the download failures. Here are some critical points:

• ActionNotFoundException: This error message indicates that the runner cannot locate the action at the specified URI. This means it can't find the necessary resources. The error message usually specifies the exact URL that the runner attempted to use.
• DownloadRepositoryArchive: This log entry confirms that the runner is trying to download the archive file for the action. Review the URL used in the download to verify if it points to the correct location within your Gitea setup.
• PrepareActionsRecursiveAsync: This log entry points to the actions manager, indicating a step-by-step approach to the action setup. If errors occur here, it suggests problems with action retrieval or processing. This is a common point where issues are identified.

Gitea Logs

These logs offer a server-side perspective, revealing whether the requested files are accessible and if the server is responding to download requests. These logs provide valuable context for understanding the server's interactions with the runner. Check these things in the Gitea logs:

• HTTP Requests: Look for log entries that show the runner's HTTP requests to Gitea's API. This tells you about the interaction between the runner and your Gitea instance.
• 404 Not Found Errors: If you see these errors, it means Gitea isn't serving the action files as expected. These errors are crucial, as they confirm that the files are not available at the requested URL.

Action Detail Logs

These logs provide a clear view of the actions execution, outlining each phase of the process. They confirm the version of the runner in use and pinpoint the exact moment of failure. Key indicators to check include:

• Runner Version: Confirm the runner's version to ensure compatibility with your Gitea setup. This helps you identify any potential compatibility issues that might affect action downloads.
• Download Action Repository: This indicates the runner's attempt to download a specific action repository, specifying the action and its version. Review this log entry to confirm that the runner is trying to download the correct action.

Troubleshooting Steps and Potential Solutions 💡

When DEFAULT_ACTIONS_URL is set to "self" and actions fail to download, the following steps can help you diagnose and resolve the issue. These solutions provide a path to ensuring your workflows run smoothly.

Network and DNS Verification

First, check if your runner can connect to your Gitea instance correctly. The errors could stem from network connectivity problems, such as DNS resolution or firewall issues. These problems can prevent the runner from accessing the required action files.

• Verify DNS Resolution: Ensure your runner can resolve the domain or IP address of your Gitea instance. Run a ping or nslookup command from within your runner's environment to verify DNS resolution.
• Check Network Connectivity: Confirm that your runner can connect to Gitea on the appropriate ports (usually 80 or 443). Use tools like curl or telnet to check connectivity.

Gitea Configuration Review

Double-check that your Gitea configuration is correctly set up. A misconfiguration can prevent the runner from accessing the action files. It's critical that the settings match your intended setup to prevent any download failures.

• DEFAULT_ACTIONS_URL: Confirm that this setting is accurately set to "self" in your Gitea's configuration file. If you use environment variables, make sure they are correctly defined.
• Base URL: Verify that your Gitea's APP_URL is properly set. This setting determines the base URL that the runner uses to access the Gitea API. If this setting isn't right, the runner could be looking in the wrong place.

Action and Repository Permissions

Incorrect permissions could prevent action downloads. Make sure the runner has the necessary rights to access the action repositories. These configurations must align to allow the runner to access the resources it needs.

• Repository Access: Ensure the runner has access to the action repositories within your Gitea instance. Double-check that the runner has the necessary read permissions.
• Authentication Tokens: If your Gitea instance requires authentication, verify the runner is configured to use the correct credentials. Check that the runner is correctly configured to use these tokens.

Gitea Version and Updates

Confirm that you're running a Gitea version that supports self-hosted actions. Consider checking for any known issues that might affect action downloads.

• Check for Updates: Make sure your Gitea instance is running the latest stable version. Updates may include fixes for download issues.
• Review Release Notes: Review the Gitea release notes to check for any known issues related to action downloads. This lets you know about any potential problems that the version you have may have.

Workarounds and Further Investigation

If the above steps don't resolve the issue, try the following workarounds or further investigations to identify a solution.

• Temporary Workaround: Try using an absolute URL for the action in your workflow, such as https://github.com/actions/checkout@v4, as a temporary measure. This will bypass the DEFAULT_ACTIONS_URL setting.
• Detailed Logging: Enable more detailed logging in your runner and Gitea. This can provide more insights into the process failures.
• Community Forums: Post your issue on the Gitea community forums or GitHub to get help from experienced users.

Example actions/deploy.yaml and Analysis 📝

Here's an example actions/deploy.yaml file that demonstrates a typical workflow using GitHub Actions. Let's analyze this example to ensure correct action usage and identify potential configuration errors.

name: Gitea Actions Demo
run-name: ${{ gitea.actor }} is testing out Gitea Actions 🚀
on: [push]

jobs:
  Explore-Gitea-Actions:
    runs-on: action-cluster
    container:
      image: ubuntu:24.04
      env:
        NODE_ENV: development
    steps:
      - run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event."
      - run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by Gitea!"
      - run: echo "🔎 The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
      - name: Check out repository code
        uses: actions/checkout@v4
      - run: echo "💡 The ${{ github.repository }} repository has been cloned to the runner."
      - run: echo "🖥️ The workflow is now ready to test your code on the runner."
      - run: sleep 60
      - name: List files in the repository
        run: |
          echo "github.workspace: ${{ github.workspace }}" && echo $pwd && ls $pwd
      - run: echo "🍏 This job's status is ${{ job.status }}."

Key Analysis Points

• uses: actions/checkout@v4: This line is crucial, as it specifies the action to be used. If the DEFAULT_ACTIONS_URL is incorrectly set, the runner may fail to download this action.
• runs-on: action-cluster: This specifies the runner environment. Verify that your runner is correctly configured and can access your Gitea instance.
• on: [push]: This defines when the workflow runs. Confirm that the workflow is triggered as expected and that any related errors occur during the push event.

Conclusion: Troubleshooting Gitea Action Downloads 🏁

Dealing with Gitea Actions download failures when using "self" as the DEFAULT_ACTIONS_URL can be tricky, but by systematically checking your configuration, network settings, and permissions, you can find the root cause and get your workflows running smoothly. Remember to check your logs, verify your settings, and don't hesitate to reach out to the community for help. Good luck, and happy coding!