Struct Gitea

pub struct Gitea { /* private fields */ }

Available on crate feature gitea only.

Module to work with Gitea container.

Starts an instance of Gitea, fully functional git server, with reasonable defaults and possibility to tune some configuration options.

From the Gitea documentation: Gitea is a painless, self-hosted, all-in-one software development service. It includes Git hosting, code review, team collaboration, package registry, and CI/CD. It is similar to GitHub, Bitbucket and GitLab.

By default, Gitea server container starts with the following config:

• accepts SSH (Git) protocol requests on port GITEA_SSH_PORT;
• accepts HTTP requests on port GITEA_HTTP_PORT;
• has a single configured user with admin privileges, with pre-defined username and password;
• configured git server hostname is localhost; this is a name which Gitea uses in the links to repositories;
• no repositories are created.

Additionally to defaults, it’s possible to:

• use HTTPS instead of HTTP with auto-generated self-signed certificate or provide your own certificate;
• redirect HTTP calls to HTTPS listener, if HTTPS is enabled;
• change git server hostname, which is used in various links to repos or web-server;
• provide your own admin user credentials as well as its SSH public key to authorize git calls;
• create any number of public or private repositories with provided names during server startup;
• execute set of gitea admin ... commands during server startup to customize configuration;
• add environment variables

Examples

1. Minimalistic server

use testcontainers::{runners::AsyncRunner, ImageExt};
use testcontainers_modules::gitea::{self, Gitea, GiteaRepo};

#[tokio::test]
async fn default_gitea_server() {
    // Run default container
    let gitea = Gitea::default().start().await.unwrap();
    let port = gitea
        .get_host_port_ipv4(gitea::GITEA_HTTP_PORT)
        .await
        .unwrap();
    let url = format!(
        "http://localhost:{port}/api/v1/users/{}",
        gitea::GITEA_DEFAULT_ADMIN_USERNAME
    );

    // Anonymous query Gitea API for user info
    let response = reqwest::Client::new().get(url).send().await.unwrap();
    assert_eq!(response.status(), 200);
}

2. Customized server

use testcontainers::{runners::AsyncRunner, ImageExt};
use testcontainers_modules::gitea::{self, Gitea, GiteaRepo};

#[tokio::test]
async fn gitea_server_with_custom_config() {
    // Start server container with:
    // - custom admin credentials
    // - two repos: public and private
    // - TLS enabled
    // - port mapping for HTTP and SSH
    // - custom git hostname
    let gitea = Gitea::default()
        .with_git_hostname("gitea.example.com")
        .with_admin_account("custom-admin", "password", None)
        .with_repo(GiteaRepo::Public("public-test-repo".to_string()))
        .with_repo(GiteaRepo::Private("private-test-repo".to_string()))
        .with_tls(true)
        .with_mapped_port(443, gitea::GITEA_HTTP_PORT)
        .with_mapped_port(22, gitea::GITEA_SSH_PORT)
        .start()
        .await
        .unwrap();

    // Obtain auto-created root CA certificate
    let ca = gitea.image().tls_ca().unwrap();
    let ca = reqwest::Certificate::from_pem(ca.as_bytes()).unwrap();
    // Attach custom CA to the client
    let client = reqwest::ClientBuilder::new()
        .add_root_certificate(ca)
        .build()
        .unwrap();

    // Get list of repos of particular user.
    // This query should be authorized.
    let response = client
        .get("https://localhost/api/v1/user/repos")
        .basic_auth("custom-admin", Some("password"))
        .header("Host", "gitea.example.com")
        .send()
        .await
        .unwrap();
    assert_eq!(response.status(), 200);

    let repos = response.json::<serde_json::Value>().await.unwrap();
    assert_eq!(repos.as_array().unwrap().len(), 2);
}

Implementations

impl Gitea

pub fn with_admin_account( self, username: impl Into<String>, password: impl Into<String>, public_key: Option<String>, ) -> Self

Change admin user credential to the custom provided username and password instead of using defaults.

If public_key value is provided, it will be added to the admin account.

Example

#[tokio::test]
async fn test() {
    const PUB_KEY: &str = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJRE5a67/cTbR6DpWqzBl6BTY0LE0Hg715ZI/FMK7iCH";
    let gitea = Gitea::default()
            .with_admin_account("git-admin", "nKz4SC7bkz4KSXbQ", Some(PUB_KEY))
            .start()
            .await
            .unwrap();
// ...
}

pub fn with_git_hostname(self, hostname: impl Into<String>) -> Self

Set git server hostname instead of the default localhost.

This is not a containers’ hostname, but the name which git server uses in various links like repo URLs.

pub fn with_repo(self, repo: GiteaRepo) -> Self

Create a repository during startup.

It’s possible to call this method more than once to create several repositories.

Example

#[tokio::test]
async fn test() {
    let gitea = Gitea::default()
            .with_repo(GiteaRepo::Public("example-public-repo"))
            .with_repo(GiteaRepo::Private("example-private-repo"))
            .start()
            .await
            .unwrap();
// ...
}

pub fn with_admin_command( self, command: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Add gitea admin ... command with parameters to execute after server startup.

This method is useful, for example, to create additional users or to do other admin stuff.

It’s possible to call this method more than once to add several consecutive commands.

Example

#[tokio::test]
async fn test() {
    let cmd = vec![
         "user",
         "create",
         "--username",
         "test-user",
         "--password",
         "test-password",
         "--email",
         "test@localhost",
         "--must-change-password=true",
         ]
         .into_iter()
         .map(String::from)
         .collect::<Vec<String>>();

    let gitea = Gitea::default()
        .with_admin_command(command)
        .start()
        .await
        .unwrap();
// ...
}

pub fn with_tls(self, enabled: bool) -> Self

Gitea web server will start with HTTPS listener (with auto-generated certificate), instead of the default HTTP.

If enabled is true, web server will be started with TLS listener with auto-generated self-signed certificate. If Root CA certificate is needed to ensure fully protected communications, it can be obtained by Gitea::tls_ca() method call.

Note: If TLS is enabled, additional HTTP listener will be started on port GITEA_HTTP_REDIRECT_PORT to redirect all HTTP calls to the HTTPS listener.

pub fn with_tls_certs( self, cert: impl Into<String>, key: impl Into<String>, ) -> Self

Gitea web server will start with HTTPS listener (with provided certificate), instead of the default HTTP.

cert and key are strings with PEM encoded certificate and its key. This method is similar to Gitea::with_tls() but use provided certificate instead of generating self-signed one.

Note: If TLS is enabled, additional HTTP listener will be started on port GITEA_HTTP_REDIRECT_PORT to redirect all HTTP calls to the HTTPS listener.

pub fn tls_ca(&self) -> Option<&str>

Return PEM encoded Root CA certificate of the Gitea servers’ certificate issuer.

If TLS has been enabled using Gitea::with_tls_certs() method (with auto-generated self-signed certificate), then this method returns Some option with issuer root CA certificate to verify servers’ certificate and ensure fully protected communications.

If TLS isn’t enabled or TLS is enabled with external certificate, provided using Gitea::with_tls_certs method, this method returns None since there is no known CA certificate.

Trait Implementations

impl Clone for Gitea

fn clone(&self) -> Gitea

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Gitea

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Gitea

fn default() -> Self

Returns default Gitea server setup with the following defaults:

• hostname is localhost;
• admin account username from GITEA_DEFAULT_ADMIN_USERNAME;
• admin account password from GITEA_DEFAULT_ADMIN_PASSWORD;
• without admins’ account SSH public key;
• without additional startup admin commands;
• without TLS (SSH and HTTP protocols only);
• without repositories.

impl Image for Gitea

fn name(&self) -> &str

The name of the docker image to pull from the Docker Hub registry.

fn tag(&self) -> &str

Implementations are encouraged to include a tag that will not change (i.e. NOT latest) in order to prevent test code from randomly breaking because the underlying docker suddenly changed.

fn ready_conditions(&self) -> Vec<WaitFor>

Returns a list of conditions that need to be met before a started container is considered ready.

fn copy_to_sources(&self) -> impl IntoIterator<Item = &CopyToContainer>

Returns the files to be copied into the container at startup.

fn expose_ports(&self) -> &[ContainerPort]

Returns the ports that needs to be exposed when a container is created.

fn exec_after_start( &self, _cs: ContainerState, ) -> Result<Vec<ExecCommand>, TestcontainersError>

Returns the commands that needs to be executed after a container is started i.e. commands to be run in a running container.

fn env_vars( &self, ) -> impl IntoIterator<Item = (impl Into<Cow<'_, str>>, impl Into<Cow<'_, str>>)>

Returns the environment variables that needs to be set when a container is created.

fn mounts(&self) -> impl IntoIterator<Item = &Mount>

Returns the mounts that needs to be created when a container is created.

fn entrypoint(&self) -> Option<&str>

Returns the entrypoint this image needs to be created with.

fn cmd(&self) -> impl IntoIterator<Item = impl Into<Cow<'_, str>>>

Returns the CMD this image needs to be created with.

fn exec_before_ready( &self, cs: ContainerState, ) -> Result<Vec<ExecCommand>, TestcontainersError>

Returns commands that will be executed after the container has started, but before the Image::ready_conditions are awaited for.