Codeberg > FTP

Notes for the setup of Forgejo action to update by deploying to server via commits to repo.

My AI article is a standalone (super long) page which I am adding updates to on an ongoing basis. I had a repo set for this specifically as it is bound to grow. I am using the lovely Codeberg for this ~ highly recommend it for versioning as it’s open source, private and run by good people.

I was trying to find a way to be able to do this on my mobile as I tend to find good reading while on the go, to and from work. I explored various editors first before realising that I might be able to just do this on the repo itself. All that was missing was the ability to update the online article itself ~ hence my hunt for a solution to do this.

If you’re an experienced dev, you’ll find this silly and too easy to write about ツ ~ but for me, and anyone else new to this, it was not as straight forward. This is why I am making notes of the setup I managed to figure out via various bits of reading and searching. I want to be able to do this again at some point in future and I’m not likely to remember all details without a list of steps. Hopefully it’ll be helpful for those with my level of backend knowledge ツ

The setup

Codeberg uses a system called Forgejo Actions (similar to GitHub Actions). It lfacilitates the running of automatic tasks whenever there’s a change to the repository. A small instruction file (called a workflow) that tells Codeberg to connect to the FTP server and upload the updated files whenever a change has been made, whenever a push has been completed.

details needed:

1. Codeberg logins to access the repo with the HTML file to be edited
2. FTP credentials: ftp server, username and password
3. remote path for the file to be uploaded to

Part 1: FTP credentials as secrets

Secrets are a secure way to store sensitive information (like passwords) in Codeberg without putting them directly into the code.

Step 1: Access repository on Codeberg

Navigate to the repository that contains the HTML file.

Step 2: Open the Settings

Click the Settings tab near the top of the repository page ~ at the top, the far right of the tab bar.

Step 3: Find the Secrets section

In the left sidebar, look for Actions. Forgejo Actions is disabled by default on Codeberg repositories.
You will need to enable it; go to Units > Overview and tick the checkbox.

On my first setup, upon enabling actions, I go an error which I had to fix, documenting it here for reference:

To fix it:

• Go to Code tab in your repo
• Navigate to .forgejo/workflows/deploy.yml
• Click the pencil/edit icon
• Find the line that says runs-on: ubuntu-latest
• Change it to runs-on: codeberg-tiny
• Commit the change

This nearly solved it but the runner needed to use the correct deploy path too:

• Go back to Code tab
• Navigate to .forgejo/workflows/deploy.yml
• Click the pencil/edit icon
• update the uses line to the following:
  uses: https://github.com/SamKirkland/FTP-Deploy-Action@v4.3.4

The final deploy.yml code looks something like this:

on: [push]

jobs:
  deploy:
    runs-on: codeberg-tiny
    steps:
      - uses: https://github.com/actions/checkout@v3

      - name: FTP Deploy
        uses: https://github.com/SamKirkland/FTP-Deploy-Action@v4.3.4
        with:
          server: ${{ secrets.FTP_HOST }}
          username: ${{ secrets.FTP_USER }}
          password: ${{ secrets.FTP_PASSWORD }}
          local-dir: ./
          server-dir: /your/remote/path/

Step 4: Add FTP hostname

• Click Add Secret (or New Secret)
• In the Name field, type exactly: FTP_HOST
• In the Value field, type your FTP hostname (e.g. ftp.yourdomain.com)
• Click Save

Step 5: Add FTP username

• Click Add Secret (or New Secret)
• In the Name field, type exactly: FTP_USER
• In the Value field, type your FTP username
• Click Save

Step 5: Add FTP password

• Click Add Secret (or New Secret)
• In the Name field, type exactly: FTP_PASSWORD
• In the Value field, type your FTP password
• Click Save

NOTE: The names FTP_HOST, FTP_USER, and FTP_PASSWORD must be typed exactly as shown. They are case-sensitive, and the workflow file will use these exact names.

The final setup will show the secrets ~ under Actions in Settings:

Part 2: the workflow file

Now we need to create a small file that tells Codeberg what to do whenever a change is pushed. This file lives inside a special folder in the repository.

Step 1: Navigate to your repository’s file list

Click on the Code tab (or the repository name) to go back to the main file view.

Step 2: Create the folder structure

Codeberg doesn’t let us create empty folders, so we’ll create the file and the folders at the same time. Click the + button or look for a ‘Create new file’ option. In the filename field at the top, type the full path:
.forgejo/workflows/deploy.yml
As we type the slashes, Codeberg will automatically create the folders for us.

NOTE: The dot at the beginning of .forgejo is important: it makes it a hidden folder, which is conventional for configuration files like this.

Step 3: Paste the workflow content

In the file editor, paste the following exactly:

on: [push]

jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3

  - name: FTP Deploy
    uses: SamKirkland/FTP-Deploy-Action@v4.3.4
    with:
      server: ${{ secrets.FTP_HOST }}
      username: ${{ secrets.FTP_USER }}
      password: ${{ secrets.FTP_PASSWORD }}
      local-dir: ./
      server-dir: /your/remote/path/

Step 4: Update the server-dir path

The only thing that needs to be changed in the workflow code is the last line. Replace /your/remote/path/ with the actual path on your server where the HTML file should be uploaded.

NOTE: Make sure the path ends with a forward slash /. If you’re not sure of the path, check your existing FTP client — it will show you the full remote path when you navigate to the folder.

Step 5: Save the file

Scroll down to find the Commit Changes section. Add a short message (e.g. ‘Add deployment workflow’), then click the green Commit button.

The completed setup will look like this in the code view:

Part 3: Check setup

Step 1: Go to the Actions tab

After committing the file, click on the Actions tab in the repository. We should see a workflow run has started (or is queued).

Step 2: Watch the run

Click on the run to see its progress. It will go through a couple of stages: checking out our code, then connecting to our FTP server and uploading files. The whole thing usually takes under a minute, though it may queue briefly on shared runners.

Step 3: Check for errors

If the run shows a red cross, click on it to see the log. The most common issues are:
• Wrong FTP path: double-check the server-dir value
• Typo in a secret name:make sure FTP_HOST, FTP_USER, FTP_PASSWORD are spelled exactly right
• FTP credentials incorrect: verify them by logging in manually with an FTP client

Step 4: Confirm on the website

Visit the site to confirm the files are there. If it all looks good, all done! ツ

The final workflow ~ all ready ツ

From this point on, whenever we want to add or update content on our page:
• Open repository on Codeberg (in any browser, DT or mobile)
• Find and click the HTML to edit
• Click the pencil / edit icon
• Make changes
• Click Commit ~ and that’s it.

Within a minute or so, the updated file will be on our server. No FTP client, no terminal, no laptop required ツ Sorted ツ