Interface with a Gogs instance from Elixir.

Why? 💡

We needed a way of easily to interact with our Gogs (GitHub Backup) Server from our Elixir / Phoenix Applications. This package is that interface.

Note: We were briefly tempted to write this code inside the Phoenix App that uses it, however we quickly realized that having it separate was better for testability/maintainability. Having a separate module enforces a separation of concerns with a strong "API contract". This way we know this package is well-tested, documented and maintained. And can be used and extended independently of any Elixir/Phoenix app. The Elixir/Phoenix app can treat gogs as a logically separate/independent entity with a clear interface.

What? 📦

A library for interacting with gogs (git) from our Elixir apps.

Hopefully this diagram explains how we are using the package:

For the complete list of functions, please see the docs: https://hexdocs.pm/gogs 📚

Who? 👤

This library is used by our (Phoenix) GitHub Backup App.
If you find it helpful for your project, please ⭐ on GitHub: github.com/dwyl/gogs

How? 💻

There are a couple of steps to get this working in your project.

Install ⬇️

Install the package from hex.pm, by adding gogs to your list of dependencies in mix.exs:

def deps do
  [
    {:gogs, "~> 0.6.0"}
  ]
end

Once you've saved your mix.exs file, run:

mix deps.get

Setup 🔧

For gogs to work in your Elixir/Phoenix App, you will need to have a few environment variables defined.

Required Environment Variables

See: .env_sample

There are 3 required environment variables:

1. GOGS_URL - the domain where your Gogs Server is deployed, without the protocol, e.g: gogs-server.fly.dev

2. GOGS_ACCESS_TOKEN - the REST API Access Token See: https://github.com/dwyl/gogs-server#connect-via-rest-api-https

3. GOGS_SSH_PRIVATE_KEY_PATH - absolute path to the id_rsa file on your localhost or Phoenix server instance.

@SIMON: this last env var currently not being picked up. So it will just use ~/simon/id_rsa You will need to add your public key to the Gogs instance for this to work on your localhost see: https://github.com/dwyl/gogs-server#add-ssh-key

Optional Environment Variables

GOGS_SSH_PORT

If your Gogs Server is configured with a non-standard SSH port, then you need to define it: GOGS_SSH_PORT e.g: 10022 for our Gogs Server deployed to Fly.io

You can easily discover the port by either visiting your Gogs Server Config page:
https://your-gogs-server.net/admin/config

e.g: https://gogs-server.fly.dev/admin/config

Or if you don't have admin access to the config page, simply view the ssh clone link on a repo page, e.g: https://gogs-server.fly.dev/nelsonic/public-repo

In our case the GOGS_SSH_PORT e.g: 10022.
If you don't set it, then gogs will assume TCP port 22.

GIT_TEMP_DIR_PATH

If you want to specify a directory where you want to clone git repos to, create a GIT_TEMP_DIR_PATH environment variable. e.g:

export GIT_TEMP_DIR_PATH=tmp

Note: the directory must already exist. (it won't be created if it's not there ...)

Usage

Here's basic usage example:

1. Create Repo

# Define the params for the remote repository:
org_name = "myorg"
repo_name = "pepsico-contract1234"
private = false # boolean
# Create the repo!
Gogs.remote_repo_create(org_name, repo_name, private)

⚠️ WARNING: there is currently no way to create an Organisation on the Gogs Server via REST API so the org_namemust already exists. e.g: https://gogs-server.fly.dev/myorg We will be figuring out a workaround shortly ... https://github.com/dwyl/gogs/issues/17

2. Clone Repo

git_repo_url = GogsHelpers.remote_url_ssh(org_name, repo_name)
Gogs.clone(git_repo_url)

3. Read Contents of File

TODO: https://github.com/dwyl/gogs/issues/21

3. Write to File

4. Commit Changes

5. Push to Gogs Remote

Function Reference / Docs? 📖

Rather than duplicate all the docs here, please read the complete function reference, on hexdocs: https://hexdocs.pm/gogs/Gogs.html

I'm Stuck! 🤷

As always, if anything is unclear or you are stuck getting this working, please open an issue! github.com/dwyl/gogs/issues We're here to help!

⚠️ Caution!

This package is provided "as is". We make no guarantee/warranty that it works. We cannot be held responsible for any undesirable effects of it's usage. e.g: if you use the Gogs.delete/1 it will permanently/irrecoverablydelete the repo. Use it with caution!

That being said, we are using this package in "production". It works for us an we maintain it. If you want to use it, go for it! But we cannot "support" your usage beyond answering questions on GitHub.

If you spot anything that can be improved, please open an issue, we're very happy to discuss!